요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GPL-2.0
3
===================================================================
4
The Definitive KVM (Kernel-based Virtual Machine) API Documentation
5
===================================================================
7
1. General description
8
======================
10
The kvm API is centered around different kinds of file descriptors
11
and ioctls that can be issued to these file descriptors. An initial
12
open("/dev/kvm") obtains a handle to the kvm subsystem; this handle
13
can be used to issue system ioctls. A KVM_CREATE_VM ioctl on this
14
handle will create a VM file descriptor which can be used to issue VM
15
ioctls. A KVM_CREATE_VCPU or KVM_CREATE_DEVICE ioctl on a VM fd will
16
create a virtual cpu or device and return a file descriptor pointing to
17
the new resource.
19
In other words, the kvm API is a set of ioctls that are issued to
20
different kinds of file descriptor in order to control various aspects of
21
a virtual machine. Depending on the file descriptor that accepts them,
22
ioctls belong to the following classes:
24
- System ioctls: These query and set global attributes which affect the
25
whole kvm subsystem. In addition a system ioctl is used to create
26
virtual machines.
28
- VM ioctls: These query and set attributes that affect an entire virtual
29
machine, for example memory layout. In addition a VM ioctl is used to
30
create virtual cpus (vcpus) and devices.
32
VM ioctls must be issued from the same process (address space) that was
33
used to create the VM.
35
- vcpu ioctls: These query and set attributes that control the operation
36
of a single virtual cpu.
38
vcpu ioctls should be issued from the same thread that was used to create
39
the vcpu, except for asynchronous vcpu ioctl that are marked as such in
40
the documentation. Otherwise, the first ioctl after switching threads
41
could see a performance impact.
43
- device ioctls: These query and set attributes that control the operation
44
of a single device.
46
device ioctls must be issued from the same process (address space) that
47
was used to create the VM.
49
While most ioctls are specific to one kind of file descriptor, in some
50
cases the same ioctl can belong to more than one class.
52
The KVM API grew over time. For this reason, KVM defines many constants
53
of the form ``KVM_CAP_*``, each corresponding to a set of functionality
54
provided by one or more ioctls. Availability of these "capabilities" can
55
be checked with :ref:`KVM_CHECK_EXTENSION <KVM_CHECK_EXTENSION>`. Some
56
capabilities also need to be enabled for VMs or VCPUs where their
57
functionality is desired (see :ref:`cap_enable` and :ref:`cap_enable_vm`).
60
2. Restrictions
61
===============
63
In general file descriptors can be migrated among processes by means
64
of fork() and the SCM_RIGHTS facility of unix domain socket. These
65
kinds of tricks are explicitly not supported by kvm. While they will
66
not cause harm to the host, their actual behavior is not guaranteed by
67
the API. See "General description" for details on the ioctl usage
68
model that is supported by KVM.
70
It is important to note that although VM ioctls may only be issued from
71
the process that created the VM, a VM's lifecycle is associated with its
72
file descriptor, not its creator (process). In other words, the VM and
73
its resources, *including the associated address space*, are not freed
74
until the last reference to the VM's file descriptor has been released.
75
For example, if fork() is issued after ioctl(KVM_CREATE_VM), the VM will
76
not be freed until both the parent (original) process and its child have
77
put their references to the VM's file descriptor.
79
Because a VM's resources are not freed until the last reference to its
80
file descriptor is released, creating additional references to a VM
81
via fork(), dup(), etc... without careful consideration is strongly
82
discouraged and may have unwanted side effects, e.g. memory allocated
83
by and on behalf of the VM's process may not be freed/unaccounted when
84
the VM is shut down.
87
3. Extensions
88
=============
90
As of Linux 2.6.22, the KVM ABI has been stabilized: no backward
91
incompatible change are allowed. However, there is an extension
92
facility that allows backward-compatible extensions to the API to be
93
queried and used.
95
The extension mechanism is not based on the Linux version number.
96
Instead, kvm defines extension identifiers and a facility to query
97
whether a particular extension identifier is available. If it is, a
98
set of ioctls is available for application use.
101
4. API description
102
==================
104
This section describes ioctls that can be used to control kvm guests.
105
For each ioctl, the following information is provided along with a
106
description:
108
Capability:
109
which KVM extension provides this ioctl. Can be 'basic',
110
which means that is will be provided by any kernel that supports
111
API version 12 (see :ref:`KVM_GET_API_VERSION <KVM_GET_API_VERSION>`),
112
or a KVM_CAP_xyz constant that can be checked with
113
:ref:`KVM_CHECK_EXTENSION <KVM_CHECK_EXTENSION>`.
115
Architectures:
116
which instruction set architectures provide this ioctl.
117
x86 includes both i386 and x86_64.
119
Type:
120
system, vm, or vcpu.
122
Parameters:
123
what parameters are accepted by the ioctl.
125
Returns:
126
the return value. General error numbers (EBADF, ENOMEM, EINVAL)
127
are not detailed, but errors with specific meanings are.
130
.. _KVM_GET_API_VERSION:
132
4.1 KVM_GET_API_VERSION
133
-----------------------
135
:Capability: basic
136
:Architectures: all
137
:Type: system ioctl
138
:Parameters: none
139
:Returns: the constant KVM_API_VERSION (=12)
141
This identifies the API version as the stable kvm API. It is not
142
expected that this number will change. However, Linux 2.6.20 and
143
2.6.21 report earlier versions; these are not documented and not
144
supported. Applications should refuse to run if KVM_GET_API_VERSION
145
returns a value other than 12. If this check passes, all ioctls
146
described as 'basic' will be available.
149
4.2 KVM_CREATE_VM
150
-----------------
152
:Capability: basic
153
:Architectures: all
154
:Type: system ioctl
155
:Parameters: machine type identifier (KVM_VM_*)
156
:Returns: a VM fd that can be used to control the new virtual machine.
158
The new VM has no virtual cpus and no memory.
159
You probably want to use 0 as machine type.
161
X86:
162
^^^^
164
Supported X86 VM types can be queried via KVM_CAP_VM_TYPES.
166
S390:
167
^^^^^
169
In order to create user controlled virtual machines on S390, check
170
KVM_CAP_S390_UCONTROL and use the flag KVM_VM_S390_UCONTROL as
171
privileged user (CAP_SYS_ADMIN).
173
MIPS:
174
^^^^^
176
To use hardware assisted virtualization on MIPS (VZ ASE) rather than
177
the default trap & emulate implementation (which changes the virtual
178
memory layout to fit in user mode), check KVM_CAP_MIPS_VZ and use the
179
flag KVM_VM_MIPS_VZ.
181
ARM64:
182
^^^^^^
184
On arm64, the physical address size for a VM (IPA Size limit) is limited
185
to 40bits by default. The limit can be configured if the host supports the
186
extension KVM_CAP_ARM_VM_IPA_SIZE. When supported, use
187
KVM_VM_TYPE_ARM_IPA_SIZE(IPA_Bits) to set the size in the machine type
188
identifier, where IPA_Bits is the maximum width of any physical
189
address used by the VM. The IPA_Bits is encoded in bits[7-0] of the
190
machine type identifier.
192
e.g, to configure a guest to use 48bit physical address size::
194
vm_fd = ioctl(dev_fd, KVM_CREATE_VM, KVM_VM_TYPE_ARM_IPA_SIZE(48));
196
The requested size (IPA_Bits) must be:
198
== =========================================================
199
0 Implies default size, 40bits (for backward compatibility)
200
N Implies N bits, where N is a positive integer such that,
201
32 <= N <= Host_IPA_Limit
202
== =========================================================
204
Host_IPA_Limit is the maximum possible value for IPA_Bits on the host and
205
is dependent on the CPU capability and the kernel configuration. The limit can
206
be retrieved using KVM_CAP_ARM_VM_IPA_SIZE of the KVM_CHECK_EXTENSION
207
ioctl() at run-time.
209
Creation of the VM will fail if the requested IPA size (whether it is
210
implicit or explicit) is unsupported on the host.
212
Please note that configuring the IPA size does not affect the capability
213
exposed by the guest CPUs in ID_AA64MMFR0_EL1[PARange]. It only affects
214
size of the address translated by the stage2 level (guest physical to
215
host physical address translations).
218
4.3 KVM_GET_MSR_INDEX_LIST, KVM_GET_MSR_FEATURE_INDEX_LIST
219
----------------------------------------------------------
221
:Capability: basic, KVM_CAP_GET_MSR_FEATURES for KVM_GET_MSR_FEATURE_INDEX_LIST
222
:Architectures: x86
223
:Type: system ioctl
224
:Parameters: struct kvm_msr_list (in/out)
225
:Returns: 0 on success; -1 on error
227
Errors:
229
====== ============================================================
230
EFAULT the msr index list cannot be read from or written to
231
E2BIG the msr index list is too big to fit in the array specified by
232
the user.
233
====== ============================================================
235
::
237
struct kvm_msr_list {
238
__u32 nmsrs; /* number of msrs in entries */
239
__u32 indices[0];
240
};
242
The user fills in the size of the indices array in nmsrs, and in return
243
kvm adjusts nmsrs to reflect the actual number of msrs and fills in the
244
indices array with their numbers.
246
KVM_GET_MSR_INDEX_LIST returns the guest msrs that are supported. The list
247
varies by kvm version and host processor, but does not change otherwise.
249
Note: if kvm indicates supports MCE (KVM_CAP_MCE), then the MCE bank MSRs are
250
not returned in the MSR list, as different vcpus can have a different number
251
of banks, as set via the KVM_X86_SETUP_MCE ioctl.
253
KVM_GET_MSR_FEATURE_INDEX_LIST returns the list of MSRs that can be passed
254
to the KVM_GET_MSRS system ioctl. This lets userspace probe host capabilities
255
and processor features that are exposed via MSRs (e.g., VMX capabilities).
256
This list also varies by kvm version and host processor, but does not change
257
otherwise.
260
.. _KVM_CHECK_EXTENSION:
262
4.4 KVM_CHECK_EXTENSION
263
-----------------------
265
:Capability: basic, KVM_CAP_CHECK_EXTENSION_VM for vm ioctl
266
:Architectures: all
267
:Type: system ioctl, vm ioctl
268
:Parameters: extension identifier (KVM_CAP_*)
269
:Returns: 0 if unsupported; 1 (or some other positive integer) if supported
271
The API allows the application to query about extensions to the core
272
kvm API. Userspace passes an extension identifier (an integer) and
273
receives an integer that describes the extension availability.
274
Generally 0 means no and 1 means yes, but some extensions may report
275
additional information in the integer return value.
277
Based on their initialization different VMs may have different capabilities.
278
It is thus encouraged to use the vm ioctl to query for capabilities (available
279
with KVM_CAP_CHECK_EXTENSION_VM on the vm fd)
281
4.5 KVM_GET_VCPU_MMAP_SIZE
282
--------------------------
284
:Capability: basic
285
:Architectures: all
286
:Type: system ioctl
287
:Parameters: none
288
:Returns: size of vcpu mmap area, in bytes
290
The KVM_RUN ioctl (cf.) communicates with userspace via a shared
291
memory region. This ioctl returns the size of that region. See the
292
KVM_RUN documentation for details.
294
Besides the size of the KVM_RUN communication region, other areas of
295
the VCPU file descriptor can be mmap-ed, including:
297
- if KVM_CAP_COALESCED_MMIO is available, a page at
298
KVM_COALESCED_MMIO_PAGE_OFFSET * PAGE_SIZE; for historical reasons,
299
this page is included in the result of KVM_GET_VCPU_MMAP_SIZE.
300
KVM_CAP_COALESCED_MMIO is not documented yet.
302
- if KVM_CAP_DIRTY_LOG_RING is available, a number of pages at
303
KVM_DIRTY_LOG_PAGE_OFFSET * PAGE_SIZE. For more information on
304
KVM_CAP_DIRTY_LOG_RING, see :ref:`KVM_CAP_DIRTY_LOG_RING`.
307
4.7 KVM_CREATE_VCPU
308
-------------------
310
:Capability: basic
311
:Architectures: all
312
:Type: vm ioctl
313
:Parameters: vcpu id (apic id on x86)
314
:Returns: vcpu fd on success, -1 on error
316
This API adds a vcpu to a virtual machine. No more than max_vcpus may be added.
317
The vcpu id is an integer in the range [0, max_vcpu_id).
319
The recommended max_vcpus value can be retrieved using the KVM_CAP_NR_VCPUS of
320
the KVM_CHECK_EXTENSION ioctl() at run-time.
321
The maximum possible value for max_vcpus can be retrieved using the
322
KVM_CAP_MAX_VCPUS of the KVM_CHECK_EXTENSION ioctl() at run-time.
324
If the KVM_CAP_NR_VCPUS does not exist, you should assume that max_vcpus is 4
325
cpus max.
326
If the KVM_CAP_MAX_VCPUS does not exist, you should assume that max_vcpus is
327
same as the value returned from KVM_CAP_NR_VCPUS.
329
The maximum possible value for max_vcpu_id can be retrieved using the
330
KVM_CAP_MAX_VCPU_ID of the KVM_CHECK_EXTENSION ioctl() at run-time.
332
If the KVM_CAP_MAX_VCPU_ID does not exist, you should assume that max_vcpu_id
333
is the same as the value returned from KVM_CAP_MAX_VCPUS.
335
On powerpc using book3s_hv mode, the vcpus are mapped onto virtual
336
threads in one or more virtual CPU cores. (This is because the
337
hardware requires all the hardware threads in a CPU core to be in the
338
same partition.) The KVM_CAP_PPC_SMT capability indicates the number
339
of vcpus per virtual core (vcore). The vcore id is obtained by
340
dividing the vcpu id by the number of vcpus per vcore. The vcpus in a
341
given vcore will always be in the same physical core as each other
342
(though that might be a different physical core from time to time).
343
Userspace can control the threading (SMT) mode of the guest by its
344
allocation of vcpu ids. For example, if userspace wants
345
single-threaded guest vcpus, it should make all vcpu ids be a multiple
346
of the number of vcpus per vcore.
348
For virtual cpus that have been created with S390 user controlled virtual
349
machines, the resulting vcpu fd can be memory mapped at page offset
350
KVM_S390_SIE_PAGE_OFFSET in order to obtain a memory map of the virtual
351
cpu's hardware control block.
354
4.8 KVM_GET_DIRTY_LOG
355
---------------------
357
:Capability: basic
358
:Architectures: all
359
:Type: vm ioctl
360
:Parameters: struct kvm_dirty_log (in/out)
361
:Returns: 0 on success, -1 on error
363
::
365
/* for KVM_GET_DIRTY_LOG */
366
struct kvm_dirty_log {
367
__u32 slot;
368
__u32 padding;
369
union {
370
void __user *dirty_bitmap; /* one bit per page */
371
__u64 padding;
372
};
373
};
375
Given a memory slot, return a bitmap containing any pages dirtied
376
since the last call to this ioctl. Bit 0 is the first page in the
377
memory slot. Ensure the entire structure is cleared to avoid padding
378
issues.
380
If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 of slot field specifies
381
the address space for which you want to return the dirty bitmap. See
382
KVM_SET_USER_MEMORY_REGION for details on the usage of slot field.
384
The bits in the dirty bitmap are cleared before the ioctl returns, unless
385
KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 is enabled. For more information,
386
see the description of the capability.
388
Note that the Xen shared_info page, if configured, shall always be assumed
389
to be dirty. KVM will not explicitly mark it such.
392
4.10 KVM_RUN
393
------------
395
:Capability: basic
396
:Architectures: all
397
:Type: vcpu ioctl
398
:Parameters: none
399
:Returns: 0 on success, -1 on error
401
Errors:
403
======= ==============================================================
404
EINTR an unmasked signal is pending
405
ENOEXEC the vcpu hasn't been initialized or the guest tried to execute
406
instructions from device memory (arm64)
407
ENOSYS data abort outside memslots with no syndrome info and
408
KVM_CAP_ARM_NISV_TO_USER not enabled (arm64)
409
EPERM SVE feature set but not finalized (arm64)
410
======= ==============================================================
412
This ioctl is used to run a guest virtual cpu. While there are no
413
explicit parameters, there is an implicit parameter block that can be
414
obtained by mmap()ing the vcpu fd at offset 0, with the size given by
415
KVM_GET_VCPU_MMAP_SIZE. The parameter block is formatted as a 'struct
416
kvm_run' (see below).
419
4.11 KVM_GET_REGS
420
-----------------
422
:Capability: basic
423
:Architectures: all except arm64
424
:Type: vcpu ioctl
425
:Parameters: struct kvm_regs (out)
426
:Returns: 0 on success, -1 on error
428
Reads the general purpose registers from the vcpu.
430
::
432
/* x86 */
433
struct kvm_regs {
434
/* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
435
__u64 rax, rbx, rcx, rdx;
436
__u64 rsi, rdi, rsp, rbp;
437
__u64 r8, r9, r10, r11;
438
__u64 r12, r13, r14, r15;
439
__u64 rip, rflags;
440
};
442
/* mips */
443
struct kvm_regs {
444
/* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
445
__u64 gpr[32];
446
__u64 hi;
447
__u64 lo;
448
__u64 pc;
449
};
451
/* LoongArch */
452
struct kvm_regs {
453
/* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
454
unsigned long gpr[32];
455
unsigned long pc;
456
};
459
4.12 KVM_SET_REGS
460
-----------------
462
:Capability: basic
463
:Architectures: all except arm64
464
:Type: vcpu ioctl
465
:Parameters: struct kvm_regs (in)
466
:Returns: 0 on success, -1 on error
468
Writes the general purpose registers into the vcpu.
470
See KVM_GET_REGS for the data structure.
473
4.13 KVM_GET_SREGS
474
------------------
476
:Capability: basic
477
:Architectures: x86, ppc
478
:Type: vcpu ioctl
479
:Parameters: struct kvm_sregs (out)
480
:Returns: 0 on success, -1 on error
482
Reads special registers from the vcpu.
484
::
486
/* x86 */
487
struct kvm_sregs {
488
struct kvm_segment cs, ds, es, fs, gs, ss;
489
struct kvm_segment tr, ldt;
490
struct kvm_dtable gdt, idt;
491
__u64 cr0, cr2, cr3, cr4, cr8;
492
__u64 efer;
493
__u64 apic_base;
494
__u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64];
495
};
497
/* ppc -- see arch/powerpc/include/uapi/asm/kvm.h */
499
interrupt_bitmap is a bitmap of pending external interrupts. At most
500
one bit may be set. This interrupt has been acknowledged by the APIC
501
but not yet injected into the cpu core.
504
4.14 KVM_SET_SREGS
505
------------------
507
:Capability: basic
508
:Architectures: x86, ppc
509
:Type: vcpu ioctl
510
:Parameters: struct kvm_sregs (in)
511
:Returns: 0 on success, -1 on error
513
Writes special registers into the vcpu. See KVM_GET_SREGS for the
514
data structures.
517
4.15 KVM_TRANSLATE
518
------------------
520
:Capability: basic
521
:Architectures: x86
522
:Type: vcpu ioctl
523
:Parameters: struct kvm_translation (in/out)
524
:Returns: 0 on success, -1 on error
526
Translates a virtual address according to the vcpu's current address
527
translation mode.
529
::
531
struct kvm_translation {
532
/* in */
533
__u64 linear_address;
535
/* out */
536
__u64 physical_address;
537
__u8 valid;
538
__u8 writeable;
539
__u8 usermode;
540
__u8 pad[5];
541
};
544
4.16 KVM_INTERRUPT
545
------------------
547
:Capability: basic
548
:Architectures: x86, ppc, mips, riscv, loongarch
549
:Type: vcpu ioctl
550
:Parameters: struct kvm_interrupt (in)
551
:Returns: 0 on success, negative on failure.
553
Queues a hardware interrupt vector to be injected.
555
::
557
/* for KVM_INTERRUPT */
558
struct kvm_interrupt {
559
/* in */
560
__u32 irq;
561
};
563
X86:
564
^^^^
566
:Returns:
568
========= ===================================
569
0 on success,
570
-EEXIST if an interrupt is already enqueued
571
-EINVAL the irq number is invalid
572
-ENXIO if the PIC is in the kernel
573
-EFAULT if the pointer is invalid
574
========= ===================================
576
Note 'irq' is an interrupt vector, not an interrupt pin or line. This
577
ioctl is useful if the in-kernel PIC is not used.
579
PPC:
580
^^^^
582
Queues an external interrupt to be injected. This ioctl is overloaded
583
with 3 different irq values:
585
a) KVM_INTERRUPT_SET
587
This injects an edge type external interrupt into the guest once it's ready
588
to receive interrupts. When injected, the interrupt is done.
590
b) KVM_INTERRUPT_UNSET
592
This unsets any pending interrupt.
594
Only available with KVM_CAP_PPC_UNSET_IRQ.
596
c) KVM_INTERRUPT_SET_LEVEL
598
This injects a level type external interrupt into the guest context. The
599
interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET
600
is triggered.
602
Only available with KVM_CAP_PPC_IRQ_LEVEL.
604
Note that any value for 'irq' other than the ones stated above is invalid
605
and incurs unexpected behavior.
607
This is an asynchronous vcpu ioctl and can be invoked from any thread.
609
MIPS:
610
^^^^^
612
Queues an external interrupt to be injected into the virtual CPU. A negative
613
interrupt number dequeues the interrupt.
615
This is an asynchronous vcpu ioctl and can be invoked from any thread.
617
RISC-V:
618
^^^^^^^
620
Queues an external interrupt to be injected into the virtual CPU. This ioctl
621
is overloaded with 2 different irq values:
623
a) KVM_INTERRUPT_SET
625
This sets external interrupt for a virtual CPU and it will receive
626
once it is ready.
628
b) KVM_INTERRUPT_UNSET
630
This clears pending external interrupt for a virtual CPU.
632
This is an asynchronous vcpu ioctl and can be invoked from any thread.
634
LOONGARCH:
635
^^^^^^^^^^
637
Queues an external interrupt to be injected into the virtual CPU. A negative
638
interrupt number dequeues the interrupt.
640
This is an asynchronous vcpu ioctl and can be invoked from any thread.
643
4.18 KVM_GET_MSRS
644
-----------------
646
:Capability: basic (vcpu), KVM_CAP_GET_MSR_FEATURES (system)
647
:Architectures: x86
648
:Type: system ioctl, vcpu ioctl
649
:Parameters: struct kvm_msrs (in/out)
650
:Returns: number of msrs successfully returned;
651
-1 on error
653
When used as a system ioctl:
654
Reads the values of MSR-based features that are available for the VM. This
655
is similar to KVM_GET_SUPPORTED_CPUID, but it returns MSR indices and values.
656
The list of msr-based features can be obtained using KVM_GET_MSR_FEATURE_INDEX_LIST
657
in a system ioctl.
659
When used as a vcpu ioctl:
660
Reads model-specific registers from the vcpu. Supported msr indices can
661
be obtained using KVM_GET_MSR_INDEX_LIST in a system ioctl.
663
::
665
struct kvm_msrs {
666
__u32 nmsrs; /* number of msrs in entries */
667
__u32 pad;
669
struct kvm_msr_entry entries[0];
670
};
672
struct kvm_msr_entry {
673
__u32 index;
674
__u32 reserved;
675
__u64 data;
676
};
678
Application code should set the 'nmsrs' member (which indicates the
679
size of the entries array) and the 'index' member of each array entry.
680
kvm will fill in the 'data' member.
683
4.19 KVM_SET_MSRS
684
-----------------
686
:Capability: basic
687
:Architectures: x86
688
:Type: vcpu ioctl
689
:Parameters: struct kvm_msrs (in)
690
:Returns: number of msrs successfully set (see below), -1 on error
692
Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the
693
data structures.
695
Application code should set the 'nmsrs' member (which indicates the
696
size of the entries array), and the 'index' and 'data' members of each
697
array entry.
699
It tries to set the MSRs in array entries[] one by one. If setting an MSR
700
fails, e.g., due to setting reserved bits, the MSR isn't supported/emulated
701
by KVM, etc..., it stops processing the MSR list and returns the number of
702
MSRs that have been set successfully.
705
4.20 KVM_SET_CPUID
706
------------------
708
:Capability: basic
709
:Architectures: x86
710
:Type: vcpu ioctl
711
:Parameters: struct kvm_cpuid (in)
712
:Returns: 0 on success, -1 on error
714
Defines the vcpu responses to the cpuid instruction. Applications
715
should use the KVM_SET_CPUID2 ioctl if available.
717
Caveat emptor:
718
- If this IOCTL fails, KVM gives no guarantees that previous valid CPUID
719
configuration (if there is) is not corrupted. Userspace can get a copy
720
of the resulting CPUID configuration through KVM_GET_CPUID2 in case.
721
- Using KVM_SET_CPUID{,2} after KVM_RUN, i.e. changing the guest vCPU model
722
after running the guest, may cause guest instability.
723
- Using heterogeneous CPUID configurations, modulo APIC IDs, topology, etc...
724
may cause guest instability.
726
::
728
struct kvm_cpuid_entry {
729
__u32 function;
730
__u32 eax;
731
__u32 ebx;
732
__u32 ecx;
733
__u32 edx;
734
__u32 padding;
735
};
737
/* for KVM_SET_CPUID */
738
struct kvm_cpuid {
739
__u32 nent;
740
__u32 padding;
741
struct kvm_cpuid_entry entries[0];
742
};
745
4.21 KVM_SET_SIGNAL_MASK
746
------------------------
748
:Capability: basic
749
:Architectures: all
750
:Type: vcpu ioctl
751
:Parameters: struct kvm_signal_mask (in)
752
:Returns: 0 on success, -1 on error
754
Defines which signals are blocked during execution of KVM_RUN. This
755
signal mask temporarily overrides the threads signal mask. Any
756
unblocked signal received (except SIGKILL and SIGSTOP, which retain
757
their traditional behaviour) will cause KVM_RUN to return with -EINTR.
759
Note the signal will only be delivered if not blocked by the original
760
signal mask.
762
::
764
/* for KVM_SET_SIGNAL_MASK */
765
struct kvm_signal_mask {
766
__u32 len;
767
__u8 sigset[0];
768
};
771
4.22 KVM_GET_FPU
772
----------------
774
:Capability: basic
775
:Architectures: x86, loongarch
776
:Type: vcpu ioctl
777
:Parameters: struct kvm_fpu (out)
778
:Returns: 0 on success, -1 on error
780
Reads the floating point state from the vcpu.
782
::
784
/* x86: for KVM_GET_FPU and KVM_SET_FPU */
785
struct kvm_fpu {
786
__u8 fpr[8][16];
787
__u16 fcw;
788
__u16 fsw;
789
__u8 ftwx; /* in fxsave format */
790
__u8 pad1;
791
__u16 last_opcode;
792
__u64 last_ip;
793
__u64 last_dp;
794
__u8 xmm[16][16];
795
__u32 mxcsr;
796
__u32 pad2;
797
};
799
/* LoongArch: for KVM_GET_FPU and KVM_SET_FPU */
800
struct kvm_fpu {
801
__u32 fcsr;
802
__u64 fcc;
803
struct kvm_fpureg {
804
__u64 val64[4];
805
}fpr[32];
806
};
809
4.23 KVM_SET_FPU
810
----------------
812
:Capability: basic
813
:Architectures: x86, loongarch
814
:Type: vcpu ioctl
815
:Parameters: struct kvm_fpu (in)
816
:Returns: 0 on success, -1 on error
818
Writes the floating point state to the vcpu.
820
::
822
/* x86: for KVM_GET_FPU and KVM_SET_FPU */
823
struct kvm_fpu {
824
__u8 fpr[8][16];
825
__u16 fcw;
826
__u16 fsw;
827
__u8 ftwx; /* in fxsave format */
828
__u8 pad1;
829
__u16 last_opcode;
830
__u64 last_ip;
831
__u64 last_dp;
832
__u8 xmm[16][16];
833
__u32 mxcsr;
834
__u32 pad2;
835
};
837
/* LoongArch: for KVM_GET_FPU and KVM_SET_FPU */
838
struct kvm_fpu {
839
__u32 fcsr;
840
__u64 fcc;
841
struct kvm_fpureg {
842
__u64 val64[4];
843
}fpr[32];
844
};
847
4.24 KVM_CREATE_IRQCHIP
848
-----------------------
850
:Capability: KVM_CAP_IRQCHIP, KVM_CAP_S390_IRQCHIP (s390)
851
:Architectures: x86, arm64, s390
852
:Type: vm ioctl
853
:Parameters: none
854
:Returns: 0 on success, -1 on error
856
Creates an interrupt controller model in the kernel.
857
On x86, creates a virtual ioapic, a virtual PIC (two PICs, nested), and sets up
858
future vcpus to have a local APIC. IRQ routing for GSIs 0-15 is set to both
859
PIC and IOAPIC; GSI 16-23 only go to the IOAPIC.
860
On arm64, a GICv2 is created. Any other GIC versions require the usage of
861
KVM_CREATE_DEVICE, which also supports creating a GICv2. Using
862
KVM_CREATE_DEVICE is preferred over KVM_CREATE_IRQCHIP for GICv2.
863
On s390, a dummy irq routing table is created.
865
Note that on s390 the KVM_CAP_S390_IRQCHIP vm capability needs to be enabled
866
before KVM_CREATE_IRQCHIP can be used.
869
4.25 KVM_IRQ_LINE
870
-----------------
872
:Capability: KVM_CAP_IRQCHIP
873
:Architectures: x86, arm64
874
:Type: vm ioctl
875
:Parameters: struct kvm_irq_level
876
:Returns: 0 on success, -1 on error
878
Sets the level of a GSI input to the interrupt controller model in the kernel.
879
On some architectures it is required that an interrupt controller model has
880
been previously created with KVM_CREATE_IRQCHIP. Note that edge-triggered
881
interrupts require the level to be set to 1 and then back to 0.
883
On real hardware, interrupt pins can be active-low or active-high. This
884
does not matter for the level field of struct kvm_irq_level: 1 always
885
means active (asserted), 0 means inactive (deasserted).
887
x86 allows the operating system to program the interrupt polarity
888
(active-low/active-high) for level-triggered interrupts, and KVM used
889
to consider the polarity. However, due to bitrot in the handling of
890
active-low interrupts, the above convention is now valid on x86 too.
891
This is signaled by KVM_CAP_X86_IOAPIC_POLARITY_IGNORED. Userspace
892
should not present interrupts to the guest as active-low unless this
893
capability is present (or unless it is not using the in-kernel irqchip,
894
of course).
897
arm64 can signal an interrupt either at the CPU level, or at the
898
in-kernel irqchip (GIC), and for in-kernel irqchip can tell the GIC to
899
use PPIs designated for specific cpus. The irq field is interpreted
900
like this::
902
bits: | 31 ... 28 | 27 ... 24 | 23 ... 16 | 15 ... 0 |
903
field: | vcpu2_index | irq_type | vcpu_index | irq_id |
905
The irq_type field has the following values:
907
- KVM_ARM_IRQ_TYPE_CPU:
908
out-of-kernel GIC: irq_id 0 is IRQ, irq_id 1 is FIQ
909
- KVM_ARM_IRQ_TYPE_SPI:
910
in-kernel GIC: SPI, irq_id between 32 and 1019 (incl.)
911
(the vcpu_index field is ignored)
912
- KVM_ARM_IRQ_TYPE_PPI:
913
in-kernel GIC: PPI, irq_id between 16 and 31 (incl.)
915
(The irq_id field thus corresponds nicely to the IRQ ID in the ARM GIC specs)
917
In both cases, level is used to assert/deassert the line.
919
When KVM_CAP_ARM_IRQ_LINE_LAYOUT_2 is supported, the target vcpu is
920
identified as (256 * vcpu2_index + vcpu_index). Otherwise, vcpu2_index
921
must be zero.
923
Note that on arm64, the KVM_CAP_IRQCHIP capability only conditions
924
injection of interrupts for the in-kernel irqchip. KVM_IRQ_LINE can always
925
be used for a userspace interrupt controller.
927
::
929
struct kvm_irq_level {
930
union {
931
__u32 irq; /* GSI */
932
__s32 status; /* not used for KVM_IRQ_LEVEL */
933
};
934
__u32 level; /* 0 or 1 */
935
};
938
4.26 KVM_GET_IRQCHIP
939
--------------------
941
:Capability: KVM_CAP_IRQCHIP
942
:Architectures: x86
943
:Type: vm ioctl
944
:Parameters: struct kvm_irqchip (in/out)
945
:Returns: 0 on success, -1 on error
947
Reads the state of a kernel interrupt controller created with
948
KVM_CREATE_IRQCHIP into a buffer provided by the caller.
950
::
952
struct kvm_irqchip {
953
__u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
954
__u32 pad;
955
union {
956
char dummy[512]; /* reserving space */
957
struct kvm_pic_state pic;
958
struct kvm_ioapic_state ioapic;
959
} chip;
960
};
963
4.27 KVM_SET_IRQCHIP
964
--------------------
966
:Capability: KVM_CAP_IRQCHIP
967
:Architectures: x86
968
:Type: vm ioctl
969
:Parameters: struct kvm_irqchip (in)
970
:Returns: 0 on success, -1 on error
972
Sets the state of a kernel interrupt controller created with
973
KVM_CREATE_IRQCHIP from a buffer provided by the caller.
975
::
977
struct kvm_irqchip {
978
__u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
979
__u32 pad;
980
union {
981
char dummy[512]; /* reserving space */
982
struct kvm_pic_state pic;
983
struct kvm_ioapic_state ioapic;
984
} chip;
985
};
988
4.28 KVM_XEN_HVM_CONFIG
989
-----------------------
991
:Capability: KVM_CAP_XEN_HVM
992
:Architectures: x86
993
:Type: vm ioctl
994
:Parameters: struct kvm_xen_hvm_config (in)
995
:Returns: 0 on success, -1 on error
997
Sets the MSR that the Xen HVM guest uses to initialize its hypercall
998
page, and provides the starting address and size of the hypercall
999
blobs in userspace. When the guest writes the MSR, kvm copies one
1000
page of a blob (32- or 64-bit, depending on the vcpu mode) to guest
1001
memory.
1003
The MSR index must be in the range [0x40000000, 0x4fffffff], i.e. must reside
1004
in the range that is unofficially reserved for use by hypervisors. The min/max
1005
values are enumerated via KVM_XEN_MSR_MIN_INDEX and KVM_XEN_MSR_MAX_INDEX.
1007
::
1009
struct kvm_xen_hvm_config {
1010
__u32 flags;
1011
__u32 msr;
1012
__u64 blob_addr_32;
1013
__u64 blob_addr_64;
1014
__u8 blob_size_32;
1015
__u8 blob_size_64;
1016
__u8 pad2[30];
1017
};
1019
If certain flags are returned from the KVM_CAP_XEN_HVM check, they may
1020
be set in the flags field of this ioctl:
1022
The KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL flag requests KVM to generate
1023
the contents of the hypercall page automatically; hypercalls will be
1024
intercepted and passed to userspace through KVM_EXIT_XEN. In this
1025
case, all of the blob size and address fields must be zero.
1027
The KVM_XEN_HVM_CONFIG_EVTCHN_SEND flag indicates to KVM that userspace
1028
will always use the KVM_XEN_HVM_EVTCHN_SEND ioctl to deliver event
1029
channel interrupts rather than manipulating the guest's shared_info
1030
structures directly. This, in turn, may allow KVM to enable features
1031
such as intercepting the SCHEDOP_poll hypercall to accelerate PV
1032
spinlock operation for the guest. Userspace may still use the ioctl
1033
to deliver events if it was advertised, even if userspace does not
1034
send this indication that it will always do so
1036
No other flags are currently valid in the struct kvm_xen_hvm_config.
1038
4.29 KVM_GET_CLOCK
1039
------------------
1041
:Capability: KVM_CAP_ADJUST_CLOCK
1042
:Architectures: x86
1043
:Type: vm ioctl
1044
:Parameters: struct kvm_clock_data (out)
1045
:Returns: 0 on success, -1 on error
1047
Gets the current timestamp of kvmclock as seen by the current guest. In
1048
conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios
1049
such as migration.
1051
When KVM_CAP_ADJUST_CLOCK is passed to KVM_CHECK_EXTENSION, it returns the
1052
set of bits that KVM can return in struct kvm_clock_data's flag member.
1054
The following flags are defined:
1056
KVM_CLOCK_TSC_STABLE
1057
If set, the returned value is the exact kvmclock
1058
value seen by all VCPUs at the instant when KVM_GET_CLOCK was called.
1059
If clear, the returned value is simply CLOCK_MONOTONIC plus a constant
1060
offset; the offset can be modified with KVM_SET_CLOCK. KVM will try
1061
to make all VCPUs follow this clock, but the exact value read by each
1062
VCPU could differ, because the host TSC is not stable.
1064
KVM_CLOCK_REALTIME
1065
If set, the `realtime` field in the kvm_clock_data
1066
structure is populated with the value of the host's real time
1067
clocksource at the instant when KVM_GET_CLOCK was called. If clear,
1068
the `realtime` field does not contain a value.
1070
KVM_CLOCK_HOST_TSC
1071
If set, the `host_tsc` field in the kvm_clock_data
1072
structure is populated with the value of the host's timestamp counter (TSC)
1073
at the instant when KVM_GET_CLOCK was called. If clear, the `host_tsc` field
1074
does not contain a value.
1076
::
1078
struct kvm_clock_data {
1079
__u64 clock; /* kvmclock current value */
1080
__u32 flags;
1081
__u32 pad0;
1082
__u64 realtime;
1083
__u64 host_tsc;
1084
__u32 pad[4];
1085
};
1088
4.30 KVM_SET_CLOCK
1089
------------------
1091
:Capability: KVM_CAP_ADJUST_CLOCK
1092
:Architectures: x86
1093
:Type: vm ioctl
1094
:Parameters: struct kvm_clock_data (in)
1095
:Returns: 0 on success, -1 on error
1097
Sets the current timestamp of kvmclock to the value specified in its parameter.
1098
In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenarios
1099
such as migration.
1101
The following flags can be passed:
1103
KVM_CLOCK_REALTIME
1104
If set, KVM will compare the value of the `realtime` field
1105
with the value of the host's real time clocksource at the instant when
1106
KVM_SET_CLOCK was called. The difference in elapsed time is added to the final
1107
kvmclock value that will be provided to guests.
1109
Other flags returned by ``KVM_GET_CLOCK`` are accepted but ignored.
1111
::
1113
struct kvm_clock_data {
1114
__u64 clock; /* kvmclock current value */
1115
__u32 flags;
1116
__u32 pad0;
1117
__u64 realtime;
1118
__u64 host_tsc;
1119
__u32 pad[4];
1120
};
1123
4.31 KVM_GET_VCPU_EVENTS
1124
------------------------
1126
:Capability: KVM_CAP_VCPU_EVENTS
1127
:Extended by: KVM_CAP_INTR_SHADOW
1128
:Architectures: x86, arm64
1129
:Type: vcpu ioctl
1130
:Parameters: struct kvm_vcpu_events (out)
1131
:Returns: 0 on success, -1 on error
1133
X86:
1134
^^^^
1136
Gets currently pending exceptions, interrupts, and NMIs as well as related
1137
states of the vcpu.
1139
::
1141
struct kvm_vcpu_events {
1142
struct {
1143
__u8 injected;
1144
__u8 nr;
1145
__u8 has_error_code;
1146
__u8 pending;
1147
__u32 error_code;
1148
} exception;
1149
struct {
1150
__u8 injected;
1151
__u8 nr;
1152
__u8 soft;
1153
__u8 shadow;
1154
} interrupt;
1155
struct {
1156
__u8 injected;
1157
__u8 pending;
1158
__u8 masked;
1159
__u8 pad;
1160
} nmi;
1161
__u32 sipi_vector;
1162
__u32 flags;
1163
struct {
1164
__u8 smm;
1165
__u8 pending;
1166
__u8 smm_inside_nmi;
1167
__u8 latched_init;
1168
} smi;
1169
__u8 reserved[27];
1170
__u8 exception_has_payload;
1171
__u64 exception_payload;
1172
};
1174
The following bits are defined in the flags field:
1176
- KVM_VCPUEVENT_VALID_SHADOW may be set to signal that
1177
interrupt.shadow contains a valid state.
1179
- KVM_VCPUEVENT_VALID_SMM may be set to signal that smi contains a
1180
valid state.
1182
- KVM_VCPUEVENT_VALID_PAYLOAD may be set to signal that the
1183
exception_has_payload, exception_payload, and exception.pending
1184
fields contain a valid state. This bit will be set whenever
1185
KVM_CAP_EXCEPTION_PAYLOAD is enabled.
1187
- KVM_VCPUEVENT_VALID_TRIPLE_FAULT may be set to signal that the
1188
triple_fault_pending field contains a valid state. This bit will
1189
be set whenever KVM_CAP_X86_TRIPLE_FAULT_EVENT is enabled.
1191
ARM64:
1192
^^^^^^
1194
If the guest accesses a device that is being emulated by the host kernel in
1195
such a way that a real device would generate a physical SError, KVM may make
1196
a virtual SError pending for that VCPU. This system error interrupt remains
1197
pending until the guest takes the exception by unmasking PSTATE.A.
1199
Running the VCPU may cause it to take a pending SError, or make an access that
1200
causes an SError to become pending. The event's description is only valid while
1201
the VPCU is not running.
1203
This API provides a way to read and write the pending 'event' state that is not
1204
visible to the guest. To save, restore or migrate a VCPU the struct representing
1205
the state can be read then written using this GET/SET API, along with the other
1206
guest-visible registers. It is not possible to 'cancel' an SError that has been
1207
made pending.
1209
A device being emulated in user-space may also wish to generate an SError. To do
1210
this the events structure can be populated by user-space. The current state
1211
should be read first, to ensure no existing SError is pending. If an existing
1212
SError is pending, the architecture's 'Multiple SError interrupts' rules should
1213
be followed. (2.5.3 of DDI0587.a "ARM Reliability, Availability, and
1214
Serviceability (RAS) Specification").
1216
SError exceptions always have an ESR value. Some CPUs have the ability to
1217
specify what the virtual SError's ESR value should be. These systems will
1218
advertise KVM_CAP_ARM_INJECT_SERROR_ESR. In this case exception.has_esr will
1219
always have a non-zero value when read, and the agent making an SError pending
1220
should specify the ISS field in the lower 24 bits of exception.serror_esr. If
1221
the system supports KVM_CAP_ARM_INJECT_SERROR_ESR, but user-space sets the events
1222
with exception.has_esr as zero, KVM will choose an ESR.
1224
Specifying exception.has_esr on a system that does not support it will return
1225
-EINVAL. Setting anything other than the lower 24bits of exception.serror_esr
1226
will return -EINVAL.
1228
It is not possible to read back a pending external abort (injected via
1229
KVM_SET_VCPU_EVENTS or otherwise) because such an exception is always delivered
1230
directly to the virtual CPU).
1232
Calling this ioctl on a vCPU that hasn't been initialized will return
1233
-ENOEXEC.
1235
::
1237
struct kvm_vcpu_events {
1238
struct {
1239
__u8 serror_pending;
1240
__u8 serror_has_esr;
1241
__u8 ext_dabt_pending;
1242
/* Align it to 8 bytes */
1243
__u8 pad[5];
1244
__u64 serror_esr;
1245
} exception;
1246
__u32 reserved[12];
1247
};
1249
4.32 KVM_SET_VCPU_EVENTS
1250
------------------------
1252
:Capability: KVM_CAP_VCPU_EVENTS
1253
:Extended by: KVM_CAP_INTR_SHADOW
1254
:Architectures: x86, arm64
1255
:Type: vcpu ioctl
1256
:Parameters: struct kvm_vcpu_events (in)
1257
:Returns: 0 on success, -1 on error
1259
X86:
1260
^^^^
1262
Set pending exceptions, interrupts, and NMIs as well as related states of the
1263
vcpu.
1265
See KVM_GET_VCPU_EVENTS for the data structure.
1267
Fields that may be modified asynchronously by running VCPUs can be excluded
1268
from the update. These fields are nmi.pending, sipi_vector, smi.smm,
1269
smi.pending. Keep the corresponding bits in the flags field cleared to
1270
suppress overwriting the current in-kernel state. The bits are:
1272
=============================== ==================================
1273
KVM_VCPUEVENT_VALID_NMI_PENDING transfer nmi.pending to the kernel
1274
KVM_VCPUEVENT_VALID_SIPI_VECTOR transfer sipi_vector
1275
KVM_VCPUEVENT_VALID_SMM transfer the smi sub-struct.
1276
=============================== ==================================
1278
If KVM_CAP_INTR_SHADOW is available, KVM_VCPUEVENT_VALID_SHADOW can be set in
1279
the flags field to signal that interrupt.shadow contains a valid state and
1280
shall be written into the VCPU.
1282
KVM_VCPUEVENT_VALID_SMM can only be set if KVM_CAP_X86_SMM is available.
1284
If KVM_CAP_EXCEPTION_PAYLOAD is enabled, KVM_VCPUEVENT_VALID_PAYLOAD
1285
can be set in the flags field to signal that the
1286
exception_has_payload, exception_payload, and exception.pending fields
1287
contain a valid state and shall be written into the VCPU.
1289
If KVM_CAP_X86_TRIPLE_FAULT_EVENT is enabled, KVM_VCPUEVENT_VALID_TRIPLE_FAULT
1290
can be set in flags field to signal that the triple_fault field contains
1291
a valid state and shall be written into the VCPU.
1293
ARM64:
1294
^^^^^^
1296
User space may need to inject several types of events to the guest.
1298
Set the pending SError exception state for this VCPU. It is not possible to
1299
'cancel' an Serror that has been made pending.
1301
If the guest performed an access to I/O memory which could not be handled by
1302
userspace, for example because of missing instruction syndrome decode
1303
information or because there is no device mapped at the accessed IPA, then
1304
userspace can ask the kernel to inject an external abort using the address
1305
from the exiting fault on the VCPU. It is a programming error to set
1306
ext_dabt_pending after an exit which was not either KVM_EXIT_MMIO or
1307
KVM_EXIT_ARM_NISV. This feature is only available if the system supports
1308
KVM_CAP_ARM_INJECT_EXT_DABT. This is a helper which provides commonality in
1309
how userspace reports accesses for the above cases to guests, across different
1310
userspace implementations. Nevertheless, userspace can still emulate all Arm
1311
exceptions by manipulating individual registers using the KVM_SET_ONE_REG API.
1313
See KVM_GET_VCPU_EVENTS for the data structure.
1315
Calling this ioctl on a vCPU that hasn't been initialized will return
1316
-ENOEXEC.
1318
4.33 KVM_GET_DEBUGREGS
1319
----------------------
1321
:Capability: KVM_CAP_DEBUGREGS
1322
:Architectures: x86
1323
:Type: vcpu ioctl
1324
:Parameters: struct kvm_debugregs (out)
1325
:Returns: 0 on success, -1 on error
1327
Reads debug registers from the vcpu.
1329
::
1331
struct kvm_debugregs {
1332
__u64 db[4];
1333
__u64 dr6;
1334
__u64 dr7;
1335
__u64 flags;
1336
__u64 reserved[9];
1337
};
1340
4.34 KVM_SET_DEBUGREGS
1341
----------------------
1343
:Capability: KVM_CAP_DEBUGREGS
1344
:Architectures: x86
1345
:Type: vcpu ioctl
1346
:Parameters: struct kvm_debugregs (in)
1347
:Returns: 0 on success, -1 on error
1349
Writes debug registers into the vcpu.
1351
See KVM_GET_DEBUGREGS for the data structure. The flags field is unused
1352
yet and must be cleared on entry.
1355
4.35 KVM_SET_USER_MEMORY_REGION
1356
-------------------------------
1358
:Capability: KVM_CAP_USER_MEMORY
1359
:Architectures: all
1360
:Type: vm ioctl
1361
:Parameters: struct kvm_userspace_memory_region (in)
1362
:Returns: 0 on success, -1 on error
1364
::
1366
struct kvm_userspace_memory_region {
1367
__u32 slot;
1368
__u32 flags;
1369
__u64 guest_phys_addr;
1370
__u64 memory_size; /* bytes */
1371
__u64 userspace_addr; /* start of the userspace allocated memory */
1372
};
1374
/* for kvm_userspace_memory_region::flags */
1375
#define KVM_MEM_LOG_DIRTY_PAGES (1UL << 0)
1376
#define KVM_MEM_READONLY (1UL << 1)
1378
This ioctl allows the user to create, modify or delete a guest physical
1379
memory slot. Bits 0-15 of "slot" specify the slot id and this value
1380
should be less than the maximum number of user memory slots supported per
1381
VM. The maximum allowed slots can be queried using KVM_CAP_NR_MEMSLOTS.
1382
Slots may not overlap in guest physical address space.
1384
If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 of "slot"
1385
specifies the address space which is being modified. They must be
1386
less than the value that KVM_CHECK_EXTENSION returns for the
1387
KVM_CAP_MULTI_ADDRESS_SPACE capability. Slots in separate address spaces
1388
are unrelated; the restriction on overlapping slots only applies within
1389
each address space.
1391
Deleting a slot is done by passing zero for memory_size. When changing
1392
an existing slot, it may be moved in the guest physical memory space,
1393
or its flags may be modified, but it may not be resized.
1395
Memory for the region is taken starting at the address denoted by the
1396
field userspace_addr, which must point at user addressable memory for
1397
the entire memory slot size. Any object may back this memory, including
1398
anonymous memory, ordinary files, and hugetlbfs.
1400
On architectures that support a form of address tagging, userspace_addr must
1401
be an untagged address.
1403
It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr
1404
be identical. This allows large pages in the guest to be backed by large
1405
pages in the host.
1407
The flags field supports two flags: KVM_MEM_LOG_DIRTY_PAGES and
1408
KVM_MEM_READONLY. The former can be set to instruct KVM to keep track of
1409
writes to memory within the slot. See KVM_GET_DIRTY_LOG ioctl to know how to
1410
use it. The latter can be set, if KVM_CAP_READONLY_MEM capability allows it,
1411
to make a new slot read-only. In this case, writes to this memory will be
1412
posted to userspace as KVM_EXIT_MMIO exits.
1414
When the KVM_CAP_SYNC_MMU capability is available, changes in the backing of
1415
the memory region are automatically reflected into the guest. For example, an
1416
mmap() that affects the region will be made visible immediately. Another
1417
example is madvise(MADV_DROP).
1419
For TDX guest, deleting/moving memory region loses guest memory contents.
1420
Read only region isn't supported. Only as-id 0 is supported.
1422
Note: On arm64, a write generated by the page-table walker (to update
1423
the Access and Dirty flags, for example) never results in a
1424
KVM_EXIT_MMIO exit when the slot has the KVM_MEM_READONLY flag. This
1425
is because KVM cannot provide the data that would be written by the
1426
page-table walker, making it impossible to emulate the access.
1427
Instead, an abort (data abort if the cause of the page-table update
1428
was a load or a store, instruction abort if it was an instruction
1429
fetch) is injected in the guest.
1431
S390:
1432
^^^^^
1434
Returns -EINVAL or -EEXIST if the VM has the KVM_VM_S390_UCONTROL flag set.
1435
Returns -EINVAL if called on a protected VM.
1437
4.36 KVM_SET_TSS_ADDR
1438
---------------------
1440
:Capability: KVM_CAP_SET_TSS_ADDR
1441
:Architectures: x86
1442
:Type: vm ioctl
1443
:Parameters: unsigned long tss_address (in)
1444
:Returns: 0 on success, -1 on error
1446
This ioctl defines the physical address of a three-page region in the guest
1447
physical address space. The region must be within the first 4GB of the
1448
guest physical address space and must not conflict with any memory slot
1449
or any mmio address. The guest may malfunction if it accesses this memory
1450
region.
1452
This ioctl is required on Intel-based hosts. This is needed on Intel hardware
1453
because of a quirk in the virtualization implementation (see the internals
1454
documentation when it pops into existence).
1457
.. _KVM_ENABLE_CAP:
1459
4.37 KVM_ENABLE_CAP
1460
-------------------
1462
:Capability: KVM_CAP_ENABLE_CAP
1463
:Architectures: mips, ppc, s390, x86, loongarch
1464
:Type: vcpu ioctl
1465
:Parameters: struct kvm_enable_cap (in)
1466
:Returns: 0 on success; -1 on error
1468
:Capability: KVM_CAP_ENABLE_CAP_VM
1469
:Architectures: all
1470
:Type: vm ioctl
1471
:Parameters: struct kvm_enable_cap (in)
1472
:Returns: 0 on success; -1 on error
1474
.. note::
1476
Not all extensions are enabled by default. Using this ioctl the application
1477
can enable an extension, making it available to the guest.
1479
On systems that do not support this ioctl, it always fails. On systems that
1480
do support it, it only works for extensions that are supported for enablement.
1482
To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should
1483
be used.
1485
::
1487
struct kvm_enable_cap {
1488
/* in */
1489
__u32 cap;
1491
The capability that is supposed to get enabled.
1493
::
1495
__u32 flags;
1497
A bitfield indicating future enhancements. Has to be 0 for now.
1499
::
1501
__u64 args[4];
1503
Arguments for enabling a feature. If a feature needs initial values to
1504
function properly, this is the place to put them.
1506
::
1508
__u8 pad[64];
1509
};
1511
The vcpu ioctl should be used for vcpu-specific capabilities, the vm ioctl
1512
for vm-wide capabilities.
1514
4.38 KVM_GET_MP_STATE
1515
---------------------
1517
:Capability: KVM_CAP_MP_STATE
1518
:Architectures: x86, s390, arm64, riscv, loongarch
1519
:Type: vcpu ioctl
1520
:Parameters: struct kvm_mp_state (out)
1521
:Returns: 0 on success; -1 on error
1523
::
1525
struct kvm_mp_state {
1526
__u32 mp_state;
1527
};
1529
Returns the vcpu's current "multiprocessing state" (though also valid on
1530
uniprocessor guests).
1532
Possible values are:
1534
========================== ===============================================
1535
KVM_MP_STATE_RUNNABLE the vcpu is currently running
1536
[x86,arm64,riscv,loongarch]
1537
KVM_MP_STATE_UNINITIALIZED the vcpu is an application processor (AP)
1538
which has not yet received an INIT signal [x86]
1539
KVM_MP_STATE_INIT_RECEIVED the vcpu has received an INIT signal, and is
1540
now ready for a SIPI [x86]
1541
KVM_MP_STATE_HALTED the vcpu has executed a HLT instruction and
1542
is waiting for an interrupt [x86]
1543
KVM_MP_STATE_SIPI_RECEIVED the vcpu has just received a SIPI (vector
1544
accessible via KVM_GET_VCPU_EVENTS) [x86]
1545
KVM_MP_STATE_STOPPED the vcpu is stopped [s390,arm64,riscv]
1546
KVM_MP_STATE_CHECK_STOP the vcpu is in a special error state [s390]
1547
KVM_MP_STATE_OPERATING the vcpu is operating (running or halted)
1548
[s390]
1549
KVM_MP_STATE_LOAD the vcpu is in a special load/startup state
1550
[s390]
1551
KVM_MP_STATE_SUSPENDED the vcpu is in a suspend state and is waiting
1552
for a wakeup event [arm64]
1553
========================== ===============================================
1555
On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an
1556
in-kernel irqchip, the multiprocessing state must be maintained by userspace on
1557
these architectures.
1559
For arm64:
1560
^^^^^^^^^^
1562
If a vCPU is in the KVM_MP_STATE_SUSPENDED state, KVM will emulate the
1563
architectural execution of a WFI instruction.
1565
If a wakeup event is recognized, KVM will exit to userspace with a
1566
KVM_SYSTEM_EVENT exit, where the event type is KVM_SYSTEM_EVENT_WAKEUP. If
1567
userspace wants to honor the wakeup, it must set the vCPU's MP state to
1568
KVM_MP_STATE_RUNNABLE. If it does not, KVM will continue to await a wakeup
1569
event in subsequent calls to KVM_RUN.
1571
.. warning::
1573
If userspace intends to keep the vCPU in a SUSPENDED state, it is
1574
strongly recommended that userspace take action to suppress the
1575
wakeup event (such as masking an interrupt). Otherwise, subsequent
1576
calls to KVM_RUN will immediately exit with a KVM_SYSTEM_EVENT_WAKEUP
1577
event and inadvertently waste CPU cycles.
1579
Additionally, if userspace takes action to suppress a wakeup event,
1580
it is strongly recommended that it also restores the vCPU to its
1581
original state when the vCPU is made RUNNABLE again. For example,
1582
if userspace masked a pending interrupt to suppress the wakeup,
1583
the interrupt should be unmasked before returning control to the
1584
guest.
1586
For riscv:
1587
^^^^^^^^^^
1589
The only states that are valid are KVM_MP_STATE_STOPPED and
1590
KVM_MP_STATE_RUNNABLE which reflect if the vcpu is paused or not.
1592
On LoongArch, only the KVM_MP_STATE_RUNNABLE state is used to reflect
1593
whether the vcpu is runnable.
1595
4.39 KVM_SET_MP_STATE
1596
---------------------
1598
:Capability: KVM_CAP_MP_STATE
1599
:Architectures: x86, s390, arm64, riscv, loongarch
1600
:Type: vcpu ioctl
1601
:Parameters: struct kvm_mp_state (in)
1602
:Returns: 0 on success; -1 on error
1604
Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for
1605
arguments.
1607
On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an
1608
in-kernel irqchip, the multiprocessing state must be maintained by userspace on
1609
these architectures.
1611
For arm64/riscv:
1612
^^^^^^^^^^^^^^^^
1614
The only states that are valid are KVM_MP_STATE_STOPPED and
1615
KVM_MP_STATE_RUNNABLE which reflect if the vcpu should be paused or not.
1617
On LoongArch, only the KVM_MP_STATE_RUNNABLE state is used to reflect
1618
whether the vcpu is runnable.
1620
4.40 KVM_SET_IDENTITY_MAP_ADDR
1621
------------------------------
1623
:Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR
1624
:Architectures: x86
1625
:Type: vm ioctl
1626
:Parameters: unsigned long identity (in)
1627
:Returns: 0 on success, -1 on error
1629
This ioctl defines the physical address of a one-page region in the guest
1630
physical address space. The region must be within the first 4GB of the
1631
guest physical address space and must not conflict with any memory slot
1632
or any mmio address. The guest may malfunction if it accesses this memory
1633
region.
1635
Setting the address to 0 will result in resetting the address to its default
1636
(0xfffbc000).
1638
This ioctl is required on Intel-based hosts. This is needed on Intel hardware
1639
because of a quirk in the virtualization implementation (see the internals
1640
documentation when it pops into existence).
1642
Fails if any VCPU has already been created.
1644
4.41 KVM_SET_BOOT_CPU_ID
1645
------------------------
1647
:Capability: KVM_CAP_SET_BOOT_CPU_ID
1648
:Architectures: x86
1649
:Type: vm ioctl
1650
:Parameters: unsigned long vcpu_id
1651
:Returns: 0 on success, -1 on error
1653
Define which vcpu is the Bootstrap Processor (BSP). Values are the same
1654
as the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the default
1655
is vcpu 0. This ioctl has to be called before vcpu creation,
1656
otherwise it will return EBUSY error.
1659
4.42 KVM_GET_XSAVE
1660
------------------
1662
:Capability: KVM_CAP_XSAVE
1663
:Architectures: x86
1664
:Type: vcpu ioctl
1665
:Parameters: struct kvm_xsave (out)
1666
:Returns: 0 on success, -1 on error
1669
::
1671
struct kvm_xsave {
1672
__u32 region[1024];
1673
__u32 extra[0];
1674
};
1676
This ioctl would copy current vcpu's xsave struct to the userspace.
1679
4.43 KVM_SET_XSAVE
1680
------------------
1682
:Capability: KVM_CAP_XSAVE and KVM_CAP_XSAVE2
1683
:Architectures: x86
1684
:Type: vcpu ioctl
1685
:Parameters: struct kvm_xsave (in)
1686
:Returns: 0 on success, -1 on error
1688
::
1691
struct kvm_xsave {
1692
__u32 region[1024];
1693
__u32 extra[0];
1694
};
1696
This ioctl would copy userspace's xsave struct to the kernel. It copies
1697
as many bytes as are returned by KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2),
1698
when invoked on the vm file descriptor. The size value returned by
1699
KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2) will always be at least 4096.
1700
Currently, it is only greater than 4096 if a dynamic feature has been
1701
enabled with ``arch_prctl()``, but this may change in the future.
1703
The offsets of the state save areas in struct kvm_xsave follow the
1704
contents of CPUID leaf 0xD on the host.
1707
4.44 KVM_GET_XCRS
1708
-----------------
1710
:Capability: KVM_CAP_XCRS
1711
:Architectures: x86
1712
:Type: vcpu ioctl
1713
:Parameters: struct kvm_xcrs (out)
1714
:Returns: 0 on success, -1 on error
1716
::
1718
struct kvm_xcr {
1719
__u32 xcr;
1720
__u32 reserved;
1721
__u64 value;
1722
};
1724
struct kvm_xcrs {
1725
__u32 nr_xcrs;
1726
__u32 flags;
1727
struct kvm_xcr xcrs[KVM_MAX_XCRS];
1728
__u64 padding[16];
1729
};
1731
This ioctl would copy current vcpu's xcrs to the userspace.
1734
4.45 KVM_SET_XCRS
1735
-----------------
1737
:Capability: KVM_CAP_XCRS
1738
:Architectures: x86
1739
:Type: vcpu ioctl
1740
:Parameters: struct kvm_xcrs (in)
1741
:Returns: 0 on success, -1 on error
1743
::
1745
struct kvm_xcr {
1746
__u32 xcr;
1747
__u32 reserved;
1748
__u64 value;
1749
};
1751
struct kvm_xcrs {
1752
__u32 nr_xcrs;
1753
__u32 flags;
1754
struct kvm_xcr xcrs[KVM_MAX_XCRS];
1755
__u64 padding[16];
1756
};
1758
This ioctl would set vcpu's xcr to the value userspace specified.
1761
4.46 KVM_GET_SUPPORTED_CPUID
1762
----------------------------
1764
:Capability: KVM_CAP_EXT_CPUID
1765
:Architectures: x86
1766
:Type: system ioctl
1767
:Parameters: struct kvm_cpuid2 (in/out)
1768
:Returns: 0 on success, -1 on error
1770
::
1772
struct kvm_cpuid2 {
1773
__u32 nent;
1774
__u32 padding;
1775
struct kvm_cpuid_entry2 entries[0];
1776
};
1778
#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0)
1779
#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1) /* deprecated */
1780
#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2) /* deprecated */
1782
struct kvm_cpuid_entry2 {
1783
__u32 function;
1784
__u32 index;
1785
__u32 flags;
1786
__u32 eax;
1787
__u32 ebx;
1788
__u32 ecx;
1789
__u32 edx;
1790
__u32 padding[3];
1791
};
1793
This ioctl returns x86 cpuid features which are supported by both the
1794
hardware and kvm in its default configuration. Userspace can use the
1795
information returned by this ioctl to construct cpuid information (for
1796
KVM_SET_CPUID2) that is consistent with hardware, kernel, and
1797
userspace capabilities, and with user requirements (for example, the
1798
user may wish to constrain cpuid to emulate older hardware, or for
1799
feature consistency across a cluster).
1801
Dynamically-enabled feature bits need to be requested with
1802
``arch_prctl()`` before calling this ioctl. Feature bits that have not
1803
been requested are excluded from the result.
1805
Note that certain capabilities, such as KVM_CAP_X86_DISABLE_EXITS, may
1806
expose cpuid features (e.g. MONITOR) which are not supported by kvm in
1807
its default configuration. If userspace enables such capabilities, it
1808
is responsible for modifying the results of this ioctl appropriately.
1810
Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structure
1811
with the 'nent' field indicating the number of entries in the variable-size
1812
array 'entries'. If the number of entries is too low to describe the cpu
1813
capabilities, an error (E2BIG) is returned. If the number is too high,
1814
the 'nent' field is adjusted and an error (ENOMEM) is returned. If the
1815
number is just right, the 'nent' field is adjusted to the number of valid
1816
entries in the 'entries' array, which is then filled.
1818
The entries returned are the host cpuid as returned by the cpuid instruction,
1819
with unknown or unsupported features masked out. Some features (for example,
1820
x2apic), may not be present in the host cpu, but are exposed by kvm if it can
1821
emulate them efficiently. The fields in each entry are defined as follows:
1823
function:
1824
the eax value used to obtain the entry
1826
index:
1827
the ecx value used to obtain the entry (for entries that are
1828
affected by ecx)
1830
flags:
1831
an OR of zero or more of the following:
1833
KVM_CPUID_FLAG_SIGNIFCANT_INDEX:
1834
if the index field is valid
1836
eax, ebx, ecx, edx:
1837
the values returned by the cpuid instruction for
1838
this function/index combination
1840
x2APIC (CPUID leaf 1, ecx[21) and TSC deadline timer (CPUID leaf 1, ecx[24])
1841
may be returned as true, but they depend on KVM_CREATE_IRQCHIP for in-kernel
1842
emulation of the local APIC. TSC deadline timer support is also reported via::
1844
ioctl(KVM_CHECK_EXTENSION, KVM_CAP_TSC_DEADLINE_TIMER)
1846
if that returns true and you use KVM_CREATE_IRQCHIP, or if you emulate the
1847
feature in userspace, then you can enable the feature for KVM_SET_CPUID2.
1849
Enabling x2APIC in KVM_SET_CPUID2 requires KVM_CREATE_IRQCHIP as KVM doesn't
1850
support forwarding x2APIC MSR accesses to userspace, i.e. KVM does not support
1851
emulating x2APIC in userspace.
1853
4.47 KVM_PPC_GET_PVINFO
1854
-----------------------
1856
:Capability: KVM_CAP_PPC_GET_PVINFO
1857
:Architectures: ppc
1858
:Type: vm ioctl
1859
:Parameters: struct kvm_ppc_pvinfo (out)
1860
:Returns: 0 on success, !0 on error
1862
::
1864
struct kvm_ppc_pvinfo {
1865
__u32 flags;
1866
__u32 hcall[4];
1867
__u8 pad[108];
1868
};
1870
This ioctl fetches PV specific information that need to be passed to the guest
1871
using the device tree or other means from vm context.
1873
The hcall array defines 4 instructions that make up a hypercall.
1875
If any additional field gets added to this structure later on, a bit for that
1876
additional piece of information will be set in the flags bitmap.
1878
The flags bitmap is defined as::
1880
/* the host supports the ePAPR idle hcall
1881
#define KVM_PPC_PVINFO_FLAGS_EV_IDLE (1<<0)
1883
4.52 KVM_SET_GSI_ROUTING
1884
------------------------
1886
:Capability: KVM_CAP_IRQ_ROUTING
1887
:Architectures: x86 s390 arm64
1888
:Type: vm ioctl
1889
:Parameters: struct kvm_irq_routing (in)
1890
:Returns: 0 on success, -1 on error
1892
Sets the GSI routing table entries, overwriting any previously set entries.
1894
On arm64, GSI routing has the following limitation:
1896
- GSI routing does not apply to KVM_IRQ_LINE but only to KVM_IRQFD.
1898
::
1900
struct kvm_irq_routing {
1901
__u32 nr;
1902
__u32 flags;
1903
struct kvm_irq_routing_entry entries[0];
1904
};
1906
No flags are specified so far, the corresponding field must be set to zero.
1908
::
1910
struct kvm_irq_routing_entry {
1911
__u32 gsi;
1912
__u32 type;
1913
__u32 flags;
1914
__u32 pad;
1915
union {
1916
struct kvm_irq_routing_irqchip irqchip;
1917
struct kvm_irq_routing_msi msi;
1918
struct kvm_irq_routing_s390_adapter adapter;
1919
struct kvm_irq_routing_hv_sint hv_sint;
1920
struct kvm_irq_routing_xen_evtchn xen_evtchn;
1921
__u32 pad[8];
1922
} u;
1923
};
1925
/* gsi routing entry types */
1926
#define KVM_IRQ_ROUTING_IRQCHIP 1
1927
#define KVM_IRQ_ROUTING_MSI 2
1928
#define KVM_IRQ_ROUTING_S390_ADAPTER 3
1929
#define KVM_IRQ_ROUTING_HV_SINT 4
1930
#define KVM_IRQ_ROUTING_XEN_EVTCHN 5
1932
On s390, adding a KVM_IRQ_ROUTING_S390_ADAPTER is rejected on ucontrol VMs with
1933
error -EINVAL.
1935
flags:
1937
- KVM_MSI_VALID_DEVID: used along with KVM_IRQ_ROUTING_MSI routing entry
1938
type, specifies that the devid field contains a valid value. The per-VM
1939
KVM_CAP_MSI_DEVID capability advertises the requirement to provide
1940
the device ID. If this capability is not available, userspace should
1941
never set the KVM_MSI_VALID_DEVID flag as the ioctl might fail.
1942
- zero otherwise
1944
::
1946
struct kvm_irq_routing_irqchip {
1947
__u32 irqchip;
1948
__u32 pin;
1949
};
1951
struct kvm_irq_routing_msi {
1952
__u32 address_lo;
1953
__u32 address_hi;
1954
__u32 data;
1955
union {
1956
__u32 pad;
1957
__u32 devid;
1958
};
1959
};
1961
If KVM_MSI_VALID_DEVID is set, devid contains a unique device identifier
1962
for the device that wrote the MSI message. For PCI, this is usually a
1963
BDF identifier in the lower 16 bits.
1965
On x86, address_hi is ignored unless the KVM_X2APIC_API_USE_32BIT_IDS
1966
feature of KVM_CAP_X2APIC_API capability is enabled. If it is enabled,
1967
address_hi bits 31-8 provide bits 31-8 of the destination id. Bits 7-0 of
1968
address_hi must be zero.
1970
::
1972
struct kvm_irq_routing_s390_adapter {
1973
__u64 ind_addr;
1974
__u64 summary_addr;
1975
__u64 ind_offset;
1976
__u32 summary_offset;
1977
__u32 adapter_id;
1978
};
1980
struct kvm_irq_routing_hv_sint {
1981
__u32 vcpu;
1982
__u32 sint;
1983
};
1985
struct kvm_irq_routing_xen_evtchn {
1986
__u32 port;
1987
__u32 vcpu;
1988
__u32 priority;
1989
};
1992
When KVM_CAP_XEN_HVM includes the KVM_XEN_HVM_CONFIG_EVTCHN_2LEVEL bit
1993
in its indication of supported features, routing to Xen event channels
1994
is supported. Although the priority field is present, only the value
1995
KVM_XEN_HVM_CONFIG_EVTCHN_2LEVEL is supported, which means delivery by
1996
2 level event channels. FIFO event channel support may be added in
1997
the future.
2000
4.55 KVM_SET_TSC_KHZ
2001
--------------------
2003
:Capability: KVM_CAP_TSC_CONTROL / KVM_CAP_VM_TSC_CONTROL
2004
:Architectures: x86
2005
:Type: vcpu ioctl / vm ioctl
2006
:Parameters: virtual tsc_khz
2007
:Returns: 0 on success, -1 on error
2009
Specifies the tsc frequency for the virtual machine. The unit of the
2010
frequency is KHz.
2012
If the KVM_CAP_VM_TSC_CONTROL capability is advertised, this can also
2013
be used as a vm ioctl to set the initial tsc frequency of subsequently
2014
created vCPUs. Note, the vm ioctl is only allowed prior to creating vCPUs.
2016
For TSC protected Confidential Computing (CoCo) VMs where TSC frequency
2017
is configured once at VM scope and remains unchanged during VM's
2018
lifetime, the vm ioctl should be used to configure the TSC frequency
2019
and the vcpu ioctl is not supported.
2021
Example of such CoCo VMs: TDX guests.
2023
4.56 KVM_GET_TSC_KHZ
2024
--------------------
2026
:Capability: KVM_CAP_GET_TSC_KHZ / KVM_CAP_VM_TSC_CONTROL
2027
:Architectures: x86
2028
:Type: vcpu ioctl / vm ioctl
2029
:Parameters: none
2030
:Returns: virtual tsc-khz on success, negative value on error
2032
Returns the tsc frequency of the guest. The unit of the return value is
2033
KHz. If the host has unstable tsc this ioctl returns -EIO instead as an
2034
error.
2037
4.57 KVM_GET_LAPIC
2038
------------------
2040
:Capability: KVM_CAP_IRQCHIP
2041
:Architectures: x86
2042
:Type: vcpu ioctl
2043
:Parameters: struct kvm_lapic_state (out)
2044
:Returns: 0 on success, -1 on error
2046
::
2048
#define KVM_APIC_REG_SIZE 0x400
2049
struct kvm_lapic_state {
2050
char regs[KVM_APIC_REG_SIZE];
2051
};
2053
Reads the Local APIC registers and copies them into the input argument. The
2054
data format and layout are the same as documented in the architecture manual.
2056
If KVM_X2APIC_API_USE_32BIT_IDS feature of KVM_CAP_X2APIC_API is
2057
enabled, then the format of APIC_ID register depends on the APIC mode
2058
(reported by MSR_IA32_APICBASE) of its VCPU. x2APIC stores APIC ID in
2059
the APIC_ID register (bytes 32-35). xAPIC only allows an 8-bit APIC ID
2060
which is stored in bits 31-24 of the APIC register, or equivalently in
2061
byte 35 of struct kvm_lapic_state's regs field. KVM_GET_LAPIC must then
2062
be called after MSR_IA32_APICBASE has been set with KVM_SET_MSR.
2064
If KVM_X2APIC_API_USE_32BIT_IDS feature is disabled, struct kvm_lapic_state
2065
always uses xAPIC format.
2068
4.58 KVM_SET_LAPIC
2069
------------------
2071
:Capability: KVM_CAP_IRQCHIP
2072
:Architectures: x86
2073
:Type: vcpu ioctl
2074
:Parameters: struct kvm_lapic_state (in)
2075
:Returns: 0 on success, -1 on error
2077
::
2079
#define KVM_APIC_REG_SIZE 0x400
2080
struct kvm_lapic_state {
2081
char regs[KVM_APIC_REG_SIZE];
2082
};
2084
Copies the input argument into the Local APIC registers. The data format
2085
and layout are the same as documented in the architecture manual.
2087
The format of the APIC ID register (bytes 32-35 of struct kvm_lapic_state's
2088
regs field) depends on the state of the KVM_CAP_X2APIC_API capability.
2089
See the note in KVM_GET_LAPIC.
2092
4.59 KVM_IOEVENTFD
2093
------------------
2095
:Capability: KVM_CAP_IOEVENTFD
2096
:Architectures: all
2097
:Type: vm ioctl
2098
:Parameters: struct kvm_ioeventfd (in)
2099
:Returns: 0 on success, !0 on error
2101
This ioctl attaches or detaches an ioeventfd to a legal pio/mmio address
2102
within the guest. A guest write in the registered address will signal the
2103
provided event instead of triggering an exit.
2105
::
2107
struct kvm_ioeventfd {
2108
__u64 datamatch;
2109
__u64 addr; /* legal pio/mmio address */
2110
__u32 len; /* 0, 1, 2, 4, or 8 bytes */
2111
__s32 fd;
2112
__u32 flags;
2113
__u8 pad[36];
2114
};
2116
For the special case of virtio-ccw devices on s390, the ioevent is matched
2117
to a subchannel/virtqueue tuple instead.
2119
The following flags are defined::
2121
#define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch)
2122
#define KVM_IOEVENTFD_FLAG_PIO (1 << kvm_ioeventfd_flag_nr_pio)
2123
#define KVM_IOEVENTFD_FLAG_DEASSIGN (1 << kvm_ioeventfd_flag_nr_deassign)
2124
#define KVM_IOEVENTFD_FLAG_VIRTIO_CCW_NOTIFY \
2125
(1 << kvm_ioeventfd_flag_nr_virtio_ccw_notify)
2127
If datamatch flag is set, the event will be signaled only if the written value
2128
to the registered address is equal to datamatch in struct kvm_ioeventfd.
2130
For virtio-ccw devices, addr contains the subchannel id and datamatch the
2131
virtqueue index.
2133
With KVM_CAP_IOEVENTFD_ANY_LENGTH, a zero length ioeventfd is allowed, and
2134
the kernel will ignore the length of guest write and may get a faster vmexit.
2135
The speedup may only apply to specific architectures, but the ioeventfd will
2136
work anyway.
2138
4.60 KVM_DIRTY_TLB
2139
------------------
2141
:Capability: KVM_CAP_SW_TLB
2142
:Architectures: ppc
2143
:Type: vcpu ioctl
2144
:Parameters: struct kvm_dirty_tlb (in)
2145
:Returns: 0 on success, -1 on error
2147
::
2149
struct kvm_dirty_tlb {
2150
__u64 bitmap;
2151
__u32 num_dirty;
2152
};
2154
This must be called whenever userspace has changed an entry in the shared
2155
TLB, prior to calling KVM_RUN on the associated vcpu.
2157
The "bitmap" field is the userspace address of an array. This array
2158
consists of a number of bits, equal to the total number of TLB entries as
2159
determined by the last successful call to ``KVM_ENABLE_CAP(KVM_CAP_SW_TLB)``,
2160
rounded up to the nearest multiple of 64.
2162
Each bit corresponds to one TLB entry, ordered the same as in the shared TLB
2163
array.
2165
The array is little-endian: the bit 0 is the least significant bit of the
2166
first byte, bit 8 is the least significant bit of the second byte, etc.
2167
This avoids any complications with differing word sizes.
2169
The "num_dirty" field is a performance hint for KVM to determine whether it
2170
should skip processing the bitmap and just invalidate everything. It must
2171
be set to the number of set bits in the bitmap.
2174
4.62 KVM_CREATE_SPAPR_TCE
2175
-------------------------
2177
:Capability: KVM_CAP_SPAPR_TCE
2178
:Architectures: powerpc
2179
:Type: vm ioctl
2180
:Parameters: struct kvm_create_spapr_tce (in)
2181
:Returns: file descriptor for manipulating the created TCE table
2183
This creates a virtual TCE (translation control entry) table, which
2184
is an IOMMU for PAPR-style virtual I/O. It is used to translate
2185
logical addresses used in virtual I/O into guest physical addresses,
2186
and provides a scatter/gather capability for PAPR virtual I/O.
2188
::
2190
/* for KVM_CAP_SPAPR_TCE */
2191
struct kvm_create_spapr_tce {
2192
__u64 liobn;
2193
__u32 window_size;
2194
};
2196
The liobn field gives the logical IO bus number for which to create a
2197
TCE table. The window_size field specifies the size of the DMA window
2198
which this TCE table will translate - the table will contain one 64
2199
bit TCE entry for every 4kiB of the DMA window.
2201
When the guest issues an H_PUT_TCE hcall on a liobn for which a TCE
2202
table has been created using this ioctl(), the kernel will handle it
2203
in real mode, updating the TCE table. H_PUT_TCE calls for other
2204
liobns will cause a vm exit and must be handled by userspace.
2206
The return value is a file descriptor which can be passed to mmap(2)
2207
to map the created TCE table into userspace. This lets userspace read
2208
the entries written by kernel-handled H_PUT_TCE calls, and also lets
2209
userspace update the TCE table directly which is useful in some
2210
circumstances.
2213
4.64 KVM_NMI
2214
------------
2216
:Capability: KVM_CAP_USER_NMI
2217
:Architectures: x86
2218
:Type: vcpu ioctl
2219
:Parameters: none
2220
:Returns: 0 on success, -1 on error
2222
Queues an NMI on the thread's vcpu. Note this is well defined only
2223
when KVM_CREATE_IRQCHIP has not been called, since this is an interface
2224
between the virtual cpu core and virtual local APIC. After KVM_CREATE_IRQCHIP
2225
has been called, this interface is completely emulated within the kernel.
2227
To use this to emulate the LINT1 input with KVM_CREATE_IRQCHIP, use the
2228
following algorithm:
2230
- pause the vcpu
2231
- read the local APIC's state (KVM_GET_LAPIC)
2232
- check whether changing LINT1 will queue an NMI (see the LVT entry for LINT1)
2233
- if so, issue KVM_NMI
2234
- resume the vcpu
2236
Some guests configure the LINT1 NMI input to cause a panic, aiding in
2237
debugging.
2240
4.65 KVM_S390_UCAS_MAP
2241
----------------------
2243
:Capability: KVM_CAP_S390_UCONTROL
2244
:Architectures: s390
2245
:Type: vcpu ioctl
2246
:Parameters: struct kvm_s390_ucas_mapping (in)
2247
:Returns: 0 in case of success
2249
The parameter is defined like this::
2251
struct kvm_s390_ucas_mapping {
2252
__u64 user_addr;
2253
__u64 vcpu_addr;
2254
__u64 length;
2255
};
2257
This ioctl maps the memory at "user_addr" with the length "length" to
2258
the vcpu's address space starting at "vcpu_addr". All parameters need to
2259
be aligned by 1 megabyte.
2262
4.66 KVM_S390_UCAS_UNMAP
2263
------------------------
2265
:Capability: KVM_CAP_S390_UCONTROL
2266
:Architectures: s390
2267
:Type: vcpu ioctl
2268
:Parameters: struct kvm_s390_ucas_mapping (in)
2269
:Returns: 0 in case of success
2271
The parameter is defined like this::
2273
struct kvm_s390_ucas_mapping {
2274
__u64 user_addr;
2275
__u64 vcpu_addr;
2276
__u64 length;
2277
};
2279
This ioctl unmaps the memory in the vcpu's address space starting at
2280
"vcpu_addr" with the length "length". The field "user_addr" is ignored.
2281
All parameters need to be aligned by 1 megabyte.
2284
4.67 KVM_S390_VCPU_FAULT
2285
------------------------
2287
:Capability: KVM_CAP_S390_UCONTROL
2288
:Architectures: s390
2289
:Type: vcpu ioctl
2290
:Parameters: vcpu absolute address (in)
2291
:Returns: 0 in case of success
2293
This call creates a page table entry on the virtual cpu's address space
2294
(for user controlled virtual machines) or the virtual machine's address
2295
space (for regular virtual machines). This only works for minor faults,
2296
thus it's recommended to access subject memory page via the user page
2297
table upfront. This is useful to handle validity intercepts for user
2298
controlled virtual machines to fault in the virtual cpu's lowcore pages
2299
prior to calling the KVM_RUN ioctl.
2302
4.68 KVM_SET_ONE_REG
2303
--------------------
2305
:Capability: KVM_CAP_ONE_REG
2306
:Architectures: all
2307
:Type: vcpu ioctl
2308
:Parameters: struct kvm_one_reg (in)
2309
:Returns: 0 on success, negative value on failure
2311
Errors:
2313
====== ============================================================
2314
ENOENT no such register
2315
EINVAL invalid register ID, or no such register or used with VMs in
2316
protected virtualization mode on s390
2317
EPERM (arm64) register access not allowed before vcpu finalization
2318
EBUSY (riscv) changing register value not allowed after the vcpu
2319
has run at least once
2320
====== ============================================================
2322
(These error codes are indicative only: do not rely on a specific error
2323
code being returned in a specific situation.)
2325
::
2327
struct kvm_one_reg {
2328
__u64 id;
2329
__u64 addr;
2330
};
2332
Using this ioctl, a single vcpu register can be set to a specific value
2333
defined by user space with the passed in struct kvm_one_reg, where id
2334
refers to the register identifier as described below and addr is a pointer
2335
to a variable with the respective size. There can be architecture agnostic
2336
and architecture specific registers. Each have their own range of operation
2337
and their own constants and width. To keep track of the implemented
2338
registers, find a list below:
2340
======= =============================== ============
2341
Arch Register Width (bits)
2342
======= =============================== ============
2343
PPC KVM_REG_PPC_HIOR 64
2344
PPC KVM_REG_PPC_IAC1 64
2345
PPC KVM_REG_PPC_IAC2 64
2346
PPC KVM_REG_PPC_IAC3 64
2347
PPC KVM_REG_PPC_IAC4 64
2348
PPC KVM_REG_PPC_DAC1 64
2349
PPC KVM_REG_PPC_DAC2 64
2350
PPC KVM_REG_PPC_DABR 64
2351
PPC KVM_REG_PPC_DSCR 64
2352
PPC KVM_REG_PPC_PURR 64
2353
PPC KVM_REG_PPC_SPURR 64
2354
PPC KVM_REG_PPC_DAR 64
2355
PPC KVM_REG_PPC_DSISR 32
2356
PPC KVM_REG_PPC_AMR 64
2357
PPC KVM_REG_PPC_UAMOR 64
2358
PPC KVM_REG_PPC_MMCR0 64
2359
PPC KVM_REG_PPC_MMCR1 64
2360
PPC KVM_REG_PPC_MMCRA 64
2361
PPC KVM_REG_PPC_MMCR2 64
2362
PPC KVM_REG_PPC_MMCRS 64
2363
PPC KVM_REG_PPC_MMCR3 64
2364
PPC KVM_REG_PPC_SIAR 64
2365
PPC KVM_REG_PPC_SDAR 64
2366
PPC KVM_REG_PPC_SIER 64
2367
PPC KVM_REG_PPC_SIER2 64
2368
PPC KVM_REG_PPC_SIER3 64
2369
PPC KVM_REG_PPC_PMC1 32
2370
PPC KVM_REG_PPC_PMC2 32
2371
PPC KVM_REG_PPC_PMC3 32
2372
PPC KVM_REG_PPC_PMC4 32
2373
PPC KVM_REG_PPC_PMC5 32
2374
PPC KVM_REG_PPC_PMC6 32
2375
PPC KVM_REG_PPC_PMC7 32
2376
PPC KVM_REG_PPC_PMC8 32
2377
PPC KVM_REG_PPC_FPR0 64
2378
...
2379
PPC KVM_REG_PPC_FPR31 64
2380
PPC KVM_REG_PPC_VR0 128
2381
...
2382
PPC KVM_REG_PPC_VR31 128
2383
PPC KVM_REG_PPC_VSR0 128
2384
...
2385
PPC KVM_REG_PPC_VSR31 128
2386
PPC KVM_REG_PPC_FPSCR 64
2387
PPC KVM_REG_PPC_VSCR 32
2388
PPC KVM_REG_PPC_VPA_ADDR 64
2389
PPC KVM_REG_PPC_VPA_SLB 128
2390
PPC KVM_REG_PPC_VPA_DTL 128
2391
PPC KVM_REG_PPC_EPCR 32
2392
PPC KVM_REG_PPC_EPR 32
2393
PPC KVM_REG_PPC_TCR 32
2394
PPC KVM_REG_PPC_TSR 32
2395
PPC KVM_REG_PPC_OR_TSR 32
2396
PPC KVM_REG_PPC_CLEAR_TSR 32
2397
PPC KVM_REG_PPC_MAS0 32
2398
PPC KVM_REG_PPC_MAS1 32
2399
PPC KVM_REG_PPC_MAS2 64
2400
PPC KVM_REG_PPC_MAS7_3 64
2401
PPC KVM_REG_PPC_MAS4 32
2402
PPC KVM_REG_PPC_MAS6 32
2403
PPC KVM_REG_PPC_MMUCFG 32
2404
PPC KVM_REG_PPC_TLB0CFG 32
2405
PPC KVM_REG_PPC_TLB1CFG 32
2406
PPC KVM_REG_PPC_TLB2CFG 32
2407
PPC KVM_REG_PPC_TLB3CFG 32
2408
PPC KVM_REG_PPC_TLB0PS 32
2409
PPC KVM_REG_PPC_TLB1PS 32
2410
PPC KVM_REG_PPC_TLB2PS 32
2411
PPC KVM_REG_PPC_TLB3PS 32
2412
PPC KVM_REG_PPC_EPTCFG 32
2413
PPC KVM_REG_PPC_ICP_STATE 64
2414
PPC KVM_REG_PPC_VP_STATE 128
2415
PPC KVM_REG_PPC_TB_OFFSET 64
2416
PPC KVM_REG_PPC_SPMC1 32
2417
PPC KVM_REG_PPC_SPMC2 32
2418
PPC KVM_REG_PPC_IAMR 64
2419
PPC KVM_REG_PPC_TFHAR 64
2420
PPC KVM_REG_PPC_TFIAR 64
2421
PPC KVM_REG_PPC_TEXASR 64
2422
PPC KVM_REG_PPC_FSCR 64
2423
PPC KVM_REG_PPC_PSPB 32
2424
PPC KVM_REG_PPC_EBBHR 64
2425
PPC KVM_REG_PPC_EBBRR 64
2426
PPC KVM_REG_PPC_BESCR 64
2427
PPC KVM_REG_PPC_TAR 64
2428
PPC KVM_REG_PPC_DPDES 64
2429
PPC KVM_REG_PPC_DAWR 64
2430
PPC KVM_REG_PPC_DAWRX 64
2431
PPC KVM_REG_PPC_CIABR 64
2432
PPC KVM_REG_PPC_IC 64
2433
PPC KVM_REG_PPC_VTB 64
2434
PPC KVM_REG_PPC_CSIGR 64
2435
PPC KVM_REG_PPC_TACR 64
2436
PPC KVM_REG_PPC_TCSCR 64
2437
PPC KVM_REG_PPC_PID 64
2438
PPC KVM_REG_PPC_ACOP 64
2439
PPC KVM_REG_PPC_VRSAVE 32
2440
PPC KVM_REG_PPC_LPCR 32
2441
PPC KVM_REG_PPC_LPCR_64 64
2442
PPC KVM_REG_PPC_PPR 64
2443
PPC KVM_REG_PPC_ARCH_COMPAT 32
2444
PPC KVM_REG_PPC_DABRX 32
2445
PPC KVM_REG_PPC_WORT 64
2446
PPC KVM_REG_PPC_SPRG9 64
2447
PPC KVM_REG_PPC_DBSR 32
2448
PPC KVM_REG_PPC_TIDR 64
2449
PPC KVM_REG_PPC_PSSCR 64
2450
PPC KVM_REG_PPC_DEC_EXPIRY 64
2451
PPC KVM_REG_PPC_PTCR 64
2452
PPC KVM_REG_PPC_HASHKEYR 64
2453
PPC KVM_REG_PPC_HASHPKEYR 64
2454
PPC KVM_REG_PPC_DAWR1 64
2455
PPC KVM_REG_PPC_DAWRX1 64
2456
PPC KVM_REG_PPC_DEXCR 64
2457
PPC KVM_REG_PPC_TM_GPR0 64
2458
...
2459
PPC KVM_REG_PPC_TM_GPR31 64
2460
PPC KVM_REG_PPC_TM_VSR0 128
2461
...
2462
PPC KVM_REG_PPC_TM_VSR63 128
2463
PPC KVM_REG_PPC_TM_CR 64
2464
PPC KVM_REG_PPC_TM_LR 64
2465
PPC KVM_REG_PPC_TM_CTR 64
2466
PPC KVM_REG_PPC_TM_FPSCR 64
2467
PPC KVM_REG_PPC_TM_AMR 64
2468
PPC KVM_REG_PPC_TM_PPR 64
2469
PPC KVM_REG_PPC_TM_VRSAVE 64
2470
PPC KVM_REG_PPC_TM_VSCR 32
2471
PPC KVM_REG_PPC_TM_DSCR 64
2472
PPC KVM_REG_PPC_TM_TAR 64
2473
PPC KVM_REG_PPC_TM_XER 64
2475
MIPS KVM_REG_MIPS_R0 64
2476
...
2477
MIPS KVM_REG_MIPS_R31 64
2478
MIPS KVM_REG_MIPS_HI 64
2479
MIPS KVM_REG_MIPS_LO 64
2480
MIPS KVM_REG_MIPS_PC 64
2481
MIPS KVM_REG_MIPS_CP0_INDEX 32
2482
MIPS KVM_REG_MIPS_CP0_ENTRYLO0 64
2483
MIPS KVM_REG_MIPS_CP0_ENTRYLO1 64
2484
MIPS KVM_REG_MIPS_CP0_CONTEXT 64
2485
MIPS KVM_REG_MIPS_CP0_CONTEXTCONFIG 32
2486
MIPS KVM_REG_MIPS_CP0_USERLOCAL 64
2487
MIPS KVM_REG_MIPS_CP0_XCONTEXTCONFIG 64
2488
MIPS KVM_REG_MIPS_CP0_PAGEMASK 32
2489
MIPS KVM_REG_MIPS_CP0_PAGEGRAIN 32
2490
MIPS KVM_REG_MIPS_CP0_SEGCTL0 64
2491
MIPS KVM_REG_MIPS_CP0_SEGCTL1 64
2492
MIPS KVM_REG_MIPS_CP0_SEGCTL2 64
2493
MIPS KVM_REG_MIPS_CP0_PWBASE 64
2494
MIPS KVM_REG_MIPS_CP0_PWFIELD 64
2495
MIPS KVM_REG_MIPS_CP0_PWSIZE 64
2496
MIPS KVM_REG_MIPS_CP0_WIRED 32
2497
MIPS KVM_REG_MIPS_CP0_PWCTL 32
2498
MIPS KVM_REG_MIPS_CP0_HWRENA 32
2499
MIPS KVM_REG_MIPS_CP0_BADVADDR 64
2500
MIPS KVM_REG_MIPS_CP0_BADINSTR 32
2501
MIPS KVM_REG_MIPS_CP0_BADINSTRP 32
2502
MIPS KVM_REG_MIPS_CP0_COUNT 32
2503
MIPS KVM_REG_MIPS_CP0_ENTRYHI 64
2504
MIPS KVM_REG_MIPS_CP0_COMPARE 32
2505
MIPS KVM_REG_MIPS_CP0_STATUS 32
2506
MIPS KVM_REG_MIPS_CP0_INTCTL 32
2507
MIPS KVM_REG_MIPS_CP0_CAUSE 32
2508
MIPS KVM_REG_MIPS_CP0_EPC 64
2509
MIPS KVM_REG_MIPS_CP0_PRID 32
2510
MIPS KVM_REG_MIPS_CP0_EBASE 64
2511
MIPS KVM_REG_MIPS_CP0_CONFIG 32
2512
MIPS KVM_REG_MIPS_CP0_CONFIG1 32
2513
MIPS KVM_REG_MIPS_CP0_CONFIG2 32
2514
MIPS KVM_REG_MIPS_CP0_CONFIG3 32
2515
MIPS KVM_REG_MIPS_CP0_CONFIG4 32
2516
MIPS KVM_REG_MIPS_CP0_CONFIG5 32
2517
MIPS KVM_REG_MIPS_CP0_CONFIG7 32
2518
MIPS KVM_REG_MIPS_CP0_XCONTEXT 64
2519
MIPS KVM_REG_MIPS_CP0_ERROREPC 64
2520
MIPS KVM_REG_MIPS_CP0_KSCRATCH1 64
2521
MIPS KVM_REG_MIPS_CP0_KSCRATCH2 64
2522
MIPS KVM_REG_MIPS_CP0_KSCRATCH3 64
2523
MIPS KVM_REG_MIPS_CP0_KSCRATCH4 64
2524
MIPS KVM_REG_MIPS_CP0_KSCRATCH5 64
2525
MIPS KVM_REG_MIPS_CP0_KSCRATCH6 64
2526
MIPS KVM_REG_MIPS_CP0_MAAR(0..63) 64
2527
MIPS KVM_REG_MIPS_COUNT_CTL 64
2528
MIPS KVM_REG_MIPS_COUNT_RESUME 64
2529
MIPS KVM_REG_MIPS_COUNT_HZ 64
2530
MIPS KVM_REG_MIPS_FPR_32(0..31) 32
2531
MIPS KVM_REG_MIPS_FPR_64(0..31) 64
2532
MIPS KVM_REG_MIPS_VEC_128(0..31) 128
2533
MIPS KVM_REG_MIPS_FCR_IR 32
2534
MIPS KVM_REG_MIPS_FCR_CSR 32
2535
MIPS KVM_REG_MIPS_MSA_IR 32
2536
MIPS KVM_REG_MIPS_MSA_CSR 32
2537
======= =============================== ============
2539
ARM registers are mapped using the lower 32 bits. The upper 16 of that
2540
is the register group type, or coprocessor number:
2542
ARM core registers have the following id bit patterns::
2544
0x4020 0000 0010 <index into the kvm_regs struct:16>
2546
ARM 32-bit CP15 registers have the following id bit patterns::
2548
0x4020 0000 000F <zero:1> <crn:4> <crm:4> <opc1:4> <opc2:3>
2550
ARM 64-bit CP15 registers have the following id bit patterns::
2552
0x4030 0000 000F <zero:1> <zero:4> <crm:4> <opc1:4> <zero:3>
2554
ARM CCSIDR registers are demultiplexed by CSSELR value::
2556
0x4020 0000 0011 00 <csselr:8>
2558
ARM 32-bit VFP control registers have the following id bit patterns::
2560
0x4020 0000 0012 1 <regno:12>
2562
ARM 64-bit FP registers have the following id bit patterns::
2564
0x4030 0000 0012 0 <regno:12>
2566
ARM firmware pseudo-registers have the following bit pattern::
2568
0x4030 0000 0014 <regno:16>
2571
arm64 registers are mapped using the lower 32 bits. The upper 16 of
2572
that is the register group type, or coprocessor number:
2574
arm64 core/FP-SIMD registers have the following id bit patterns. Note
2575
that the size of the access is variable, as the kvm_regs structure
2576
contains elements ranging from 32 to 128 bits. The index is a 32bit
2577
value in the kvm_regs structure seen as a 32bit array::
2579
0x60x0 0000 0010 <index into the kvm_regs struct:16>
2581
Specifically:
2583
======================= ========= ===== =======================================
2584
Encoding Register Bits kvm_regs member
2585
======================= ========= ===== =======================================
2586
0x6030 0000 0010 0000 X0 64 regs.regs[0]
2587
0x6030 0000 0010 0002 X1 64 regs.regs[1]
2588
...
2589
0x6030 0000 0010 003c X30 64 regs.regs[30]
2590
0x6030 0000 0010 003e SP 64 regs.sp
2591
0x6030 0000 0010 0040 PC 64 regs.pc
2592
0x6030 0000 0010 0042 PSTATE 64 regs.pstate
2593
0x6030 0000 0010 0044 SP_EL1 64 sp_el1
2594
0x6030 0000 0010 0046 ELR_EL1 64 elr_el1
2595
0x6030 0000 0010 0048 SPSR_EL1 64 spsr[KVM_SPSR_EL1] (alias SPSR_SVC)
2596
0x6030 0000 0010 004a SPSR_ABT 64 spsr[KVM_SPSR_ABT]
2597
0x6030 0000 0010 004c SPSR_UND 64 spsr[KVM_SPSR_UND]
2598
0x6030 0000 0010 004e SPSR_IRQ 64 spsr[KVM_SPSR_IRQ]
2599
0x6030 0000 0010 0050 SPSR_FIQ 64 spsr[KVM_SPSR_FIQ]
2600
0x6040 0000 0010 0054 V0 128 fp_regs.vregs[0] [1]_
2601
0x6040 0000 0010 0058 V1 128 fp_regs.vregs[1] [1]_
2602
...
2603
0x6040 0000 0010 00d0 V31 128 fp_regs.vregs[31] [1]_
2604
0x6020 0000 0010 00d4 FPSR 32 fp_regs.fpsr
2605
0x6020 0000 0010 00d5 FPCR 32 fp_regs.fpcr
2606
======================= ========= ===== =======================================
2608
.. [1] These encodings are not accepted for SVE-enabled vcpus. See
2609
:ref:`KVM_ARM_VCPU_INIT`.
2611
The equivalent register content can be accessed via bits [127:0] of
2612
the corresponding SVE Zn registers instead for vcpus that have SVE
2613
enabled (see below).
2615
arm64 CCSIDR registers are demultiplexed by CSSELR value::
2617
0x6020 0000 0011 00 <csselr:8>
2619
arm64 system registers have the following id bit patterns::
2621
0x6030 0000 0013 <op0:2> <op1:3> <crn:4> <crm:4> <op2:3>
2623
.. warning::
2625
Two system register IDs do not follow the specified pattern. These
2626
are KVM_REG_ARM_TIMER_CVAL and KVM_REG_ARM_TIMER_CNT, which map to
2627
system registers CNTV_CVAL_EL0 and CNTVCT_EL0 respectively. These
2628
two had their values accidentally swapped, which means TIMER_CVAL is
2629
derived from the register encoding for CNTVCT_EL0 and TIMER_CNT is
2630
derived from the register encoding for CNTV_CVAL_EL0. As this is
2631
API, it must remain this way.
2633
arm64 firmware pseudo-registers have the following bit pattern::
2635
0x6030 0000 0014 <regno:16>
2637
arm64 SVE registers have the following bit patterns::
2639
0x6080 0000 0015 00 <n:5> <slice:5> Zn bits[2048*slice + 2047 : 2048*slice]
2640
0x6050 0000 0015 04 <n:4> <slice:5> Pn bits[256*slice + 255 : 256*slice]
2641
0x6050 0000 0015 060 <slice:5> FFR bits[256*slice + 255 : 256*slice]
2642
0x6060 0000 0015 ffff KVM_REG_ARM64_SVE_VLS pseudo-register
2644
Access to register IDs where 2048 * slice >= 128 * max_vq will fail with
2645
ENOENT. max_vq is the vcpu's maximum supported vector length in 128-bit
2646
quadwords: see [2]_ below.
2648
These registers are only accessible on vcpus for which SVE is enabled.
2649
See KVM_ARM_VCPU_INIT for details.
2651
In addition, except for KVM_REG_ARM64_SVE_VLS, these registers are not
2652
accessible until the vcpu's SVE configuration has been finalized
2653
using KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE). See KVM_ARM_VCPU_INIT
2654
and KVM_ARM_VCPU_FINALIZE for more information about this procedure.
2656
KVM_REG_ARM64_SVE_VLS is a pseudo-register that allows the set of vector
2657
lengths supported by the vcpu to be discovered and configured by
2658
userspace. When transferred to or from user memory via KVM_GET_ONE_REG
2659
or KVM_SET_ONE_REG, the value of this register is of type
2660
__u64[KVM_ARM64_SVE_VLS_WORDS], and encodes the set of vector lengths as
2661
follows::
2663
__u64 vector_lengths[KVM_ARM64_SVE_VLS_WORDS];
2665
if (vq >= SVE_VQ_MIN && vq <= SVE_VQ_MAX &&
2666
((vector_lengths[(vq - KVM_ARM64_SVE_VQ_MIN) / 64] >>
2667
((vq - KVM_ARM64_SVE_VQ_MIN) % 64)) & 1))
2668
/* Vector length vq * 16 bytes supported */
2669
else
2670
/* Vector length vq * 16 bytes not supported */
2672
.. [2] The maximum value vq for which the above condition is true is
2673
max_vq. This is the maximum vector length available to the guest on
2674
this vcpu, and determines which register slices are visible through
2675
this ioctl interface.
2677
(See Documentation/arch/arm64/sve.rst for an explanation of the "vq"
2678
nomenclature.)
2680
KVM_REG_ARM64_SVE_VLS is only accessible after KVM_ARM_VCPU_INIT.
2681
KVM_ARM_VCPU_INIT initialises it to the best set of vector lengths that
2682
the host supports.
2684
Userspace may subsequently modify it if desired until the vcpu's SVE
2685
configuration is finalized using KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE).
2687
Apart from simply removing all vector lengths from the host set that
2688
exceed some value, support for arbitrarily chosen sets of vector lengths
2689
is hardware-dependent and may not be available. Attempting to configure
2690
an invalid set of vector lengths via KVM_SET_ONE_REG will fail with
2691
EINVAL.
2693
After the vcpu's SVE configuration is finalized, further attempts to
2694
write this register will fail with EPERM.
2696
arm64 bitmap feature firmware pseudo-registers have the following bit pattern::
2698
0x6030 0000 0016 <regno:16>
2700
The bitmap feature firmware registers exposes the hypercall services that
2701
are available for userspace to configure. The set bits corresponds to the
2702
services that are available for the guests to access. By default, KVM
2703
sets all the supported bits during VM initialization. The userspace can
2704
discover the available services via KVM_GET_ONE_REG, and write back the
2705
bitmap corresponding to the features that it wishes guests to see via
2706
KVM_SET_ONE_REG.
2708
Note: These registers are immutable once any of the vCPUs of the VM has
2709
run at least once. A KVM_SET_ONE_REG in such a scenario will return
2710
a -EBUSY to userspace.
2712
(See Documentation/virt/kvm/arm/hypercalls.rst for more details.)
2715
MIPS registers are mapped using the lower 32 bits. The upper 16 of that is
2716
the register group type:
2718
MIPS core registers (see above) have the following id bit patterns::
2720
0x7030 0000 0000 <reg:16>
2722
MIPS CP0 registers (see KVM_REG_MIPS_CP0_* above) have the following id bit
2723
patterns depending on whether they're 32-bit or 64-bit registers::
2725
0x7020 0000 0001 00 <reg:5> <sel:3> (32-bit)
2726
0x7030 0000 0001 00 <reg:5> <sel:3> (64-bit)
2728
Note: KVM_REG_MIPS_CP0_ENTRYLO0 and KVM_REG_MIPS_CP0_ENTRYLO1 are the MIPS64
2729
versions of the EntryLo registers regardless of the word size of the host
2730
hardware, host kernel, guest, and whether XPA is present in the guest, i.e.
2731
with the RI and XI bits (if they exist) in bits 63 and 62 respectively, and
2732
the PFNX field starting at bit 30.
2734
MIPS MAARs (see KVM_REG_MIPS_CP0_MAAR(*) above) have the following id bit
2735
patterns::
2737
0x7030 0000 0001 01 <reg:8>
2739
MIPS KVM control registers (see above) have the following id bit patterns::
2741
0x7030 0000 0002 <reg:16>
2743
MIPS FPU registers (see KVM_REG_MIPS_FPR_{32,64}() above) have the following
2744
id bit patterns depending on the size of the register being accessed. They are
2745
always accessed according to the current guest FPU mode (Status.FR and
2746
Config5.FRE), i.e. as the guest would see them, and they become unpredictable
2747
if the guest FPU mode is changed. MIPS SIMD Architecture (MSA) vector
2748
registers (see KVM_REG_MIPS_VEC_128() above) have similar patterns as they
2749
overlap the FPU registers::
2751
0x7020 0000 0003 00 <0:3> <reg:5> (32-bit FPU registers)
2752
0x7030 0000 0003 00 <0:3> <reg:5> (64-bit FPU registers)
2753
0x7040 0000 0003 00 <0:3> <reg:5> (128-bit MSA vector registers)
2755
MIPS FPU control registers (see KVM_REG_MIPS_FCR_{IR,CSR} above) have the
2756
following id bit patterns::
2758
0x7020 0000 0003 01 <0:3> <reg:5>
2760
MIPS MSA control registers (see KVM_REG_MIPS_MSA_{IR,CSR} above) have the
2761
following id bit patterns::
2763
0x7020 0000 0003 02 <0:3> <reg:5>
2765
RISC-V registers are mapped using the lower 32 bits. The upper 8 bits of
2766
that is the register group type.
2768
RISC-V config registers are meant for configuring a Guest VCPU and it has
2769
the following id bit patterns::
2771
0x8020 0000 01 <index into the kvm_riscv_config struct:24> (32bit Host)
2772
0x8030 0000 01 <index into the kvm_riscv_config struct:24> (64bit Host)
2774
Following are the RISC-V config registers:
2776
======================= ========= =============================================
2777
Encoding Register Description
2778
======================= ========= =============================================
2779
0x80x0 0000 0100 0000 isa ISA feature bitmap of Guest VCPU
2780
======================= ========= =============================================
2782
The isa config register can be read anytime but can only be written before
2783
a Guest VCPU runs. It will have ISA feature bits matching underlying host
2784
set by default.
2786
RISC-V core registers represent the general execution state of a Guest VCPU
2787
and it has the following id bit patterns::
2789
0x8020 0000 02 <index into the kvm_riscv_core struct:24> (32bit Host)
2790
0x8030 0000 02 <index into the kvm_riscv_core struct:24> (64bit Host)
2792
Following are the RISC-V core registers:
2794
======================= ========= =============================================
2795
Encoding Register Description
2796
======================= ========= =============================================
2797
0x80x0 0000 0200 0000 regs.pc Program counter
2798
0x80x0 0000 0200 0001 regs.ra Return address
2799
0x80x0 0000 0200 0002 regs.sp Stack pointer
2800
0x80x0 0000 0200 0003 regs.gp Global pointer
2801
0x80x0 0000 0200 0004 regs.tp Task pointer
2802
0x80x0 0000 0200 0005 regs.t0 Caller saved register 0
2803
0x80x0 0000 0200 0006 regs.t1 Caller saved register 1
2804
0x80x0 0000 0200 0007 regs.t2 Caller saved register 2
2805
0x80x0 0000 0200 0008 regs.s0 Callee saved register 0
2806
0x80x0 0000 0200 0009 regs.s1 Callee saved register 1
2807
0x80x0 0000 0200 000a regs.a0 Function argument (or return value) 0
2808
0x80x0 0000 0200 000b regs.a1 Function argument (or return value) 1
2809
0x80x0 0000 0200 000c regs.a2 Function argument 2
2810
0x80x0 0000 0200 000d regs.a3 Function argument 3
2811
0x80x0 0000 0200 000e regs.a4 Function argument 4
2812
0x80x0 0000 0200 000f regs.a5 Function argument 5
2813
0x80x0 0000 0200 0010 regs.a6 Function argument 6
2814
0x80x0 0000 0200 0011 regs.a7 Function argument 7
2815
0x80x0 0000 0200 0012 regs.s2 Callee saved register 2
2816
0x80x0 0000 0200 0013 regs.s3 Callee saved register 3
2817
0x80x0 0000 0200 0014 regs.s4 Callee saved register 4
2818
0x80x0 0000 0200 0015 regs.s5 Callee saved register 5
2819
0x80x0 0000 0200 0016 regs.s6 Callee saved register 6
2820
0x80x0 0000 0200 0017 regs.s7 Callee saved register 7
2821
0x80x0 0000 0200 0018 regs.s8 Callee saved register 8
2822
0x80x0 0000 0200 0019 regs.s9 Callee saved register 9
2823
0x80x0 0000 0200 001a regs.s10 Callee saved register 10
2824
0x80x0 0000 0200 001b regs.s11 Callee saved register 11
2825
0x80x0 0000 0200 001c regs.t3 Caller saved register 3
2826
0x80x0 0000 0200 001d regs.t4 Caller saved register 4
2827
0x80x0 0000 0200 001e regs.t5 Caller saved register 5
2828
0x80x0 0000 0200 001f regs.t6 Caller saved register 6
2829
0x80x0 0000 0200 0020 mode Privilege mode (1 = S-mode or 0 = U-mode)
2830
======================= ========= =============================================
2832
RISC-V csr registers represent the supervisor mode control/status registers
2833
of a Guest VCPU and it has the following id bit patterns::
2835
0x8020 0000 03 <index into the kvm_riscv_csr struct:24> (32bit Host)
2836
0x8030 0000 03 <index into the kvm_riscv_csr struct:24> (64bit Host)
2838
Following are the RISC-V csr registers:
2840
======================= ========= =============================================
2841
Encoding Register Description
2842
======================= ========= =============================================
2843
0x80x0 0000 0300 0000 sstatus Supervisor status
2844
0x80x0 0000 0300 0001 sie Supervisor interrupt enable
2845
0x80x0 0000 0300 0002 stvec Supervisor trap vector base
2846
0x80x0 0000 0300 0003 sscratch Supervisor scratch register
2847
0x80x0 0000 0300 0004 sepc Supervisor exception program counter
2848
0x80x0 0000 0300 0005 scause Supervisor trap cause
2849
0x80x0 0000 0300 0006 stval Supervisor bad address or instruction
2850
0x80x0 0000 0300 0007 sip Supervisor interrupt pending
2851
0x80x0 0000 0300 0008 satp Supervisor address translation and protection
2852
======================= ========= =============================================
2854
RISC-V timer registers represent the timer state of a Guest VCPU and it has
2855
the following id bit patterns::
2857
0x8030 0000 04 <index into the kvm_riscv_timer struct:24>
2859
Following are the RISC-V timer registers:
2861
======================= ========= =============================================
2862
Encoding Register Description
2863
======================= ========= =============================================
2864
0x8030 0000 0400 0000 frequency Time base frequency (read-only)
2865
0x8030 0000 0400 0001 time Time value visible to Guest
2866
0x8030 0000 0400 0002 compare Time compare programmed by Guest
2867
0x8030 0000 0400 0003 state Time compare state (1 = ON or 0 = OFF)
2868
======================= ========= =============================================
2870
RISC-V F-extension registers represent the single precision floating point
2871
state of a Guest VCPU and it has the following id bit patterns::
2873
0x8020 0000 05 <index into the __riscv_f_ext_state struct:24>
2875
Following are the RISC-V F-extension registers:
2877
======================= ========= =============================================
2878
Encoding Register Description
2879
======================= ========= =============================================
2880
0x8020 0000 0500 0000 f[0] Floating point register 0
2881
...
2882
0x8020 0000 0500 001f f[31] Floating point register 31
2883
0x8020 0000 0500 0020 fcsr Floating point control and status register
2884
======================= ========= =============================================
2886
RISC-V D-extension registers represent the double precision floating point
2887
state of a Guest VCPU and it has the following id bit patterns::
2889
0x8020 0000 06 <index into the __riscv_d_ext_state struct:24> (fcsr)
2890
0x8030 0000 06 <index into the __riscv_d_ext_state struct:24> (non-fcsr)
2892
Following are the RISC-V D-extension registers:
2894
======================= ========= =============================================
2895
Encoding Register Description
2896
======================= ========= =============================================
2897
0x8030 0000 0600 0000 f[0] Floating point register 0
2898
...
2899
0x8030 0000 0600 001f f[31] Floating point register 31
2900
0x8020 0000 0600 0020 fcsr Floating point control and status register
2901
======================= ========= =============================================
2903
LoongArch registers are mapped using the lower 32 bits. The upper 16 bits of
2904
that is the register group type.
2906
LoongArch csr registers are used to control guest cpu or get status of guest
2907
cpu, and they have the following id bit patterns::
2909
0x9030 0000 0001 00 <reg:5> <sel:3> (64-bit)
2911
LoongArch KVM control registers are used to implement some new defined functions
2912
such as set vcpu counter or reset vcpu, and they have the following id bit patterns::
2914
0x9030 0000 0002 <reg:16>
2916
x86 MSR registers have the following id bit patterns::
2917
0x2030 0002 <msr number:32>
2919
Following are the KVM-defined registers for x86:
2921
======================= ========= =============================================
2922
Encoding Register Description
2923
======================= ========= =============================================
2924
0x2030 0003 0000 0000 SSP Shadow Stack Pointer
2925
======================= ========= =============================================
2927
4.69 KVM_GET_ONE_REG
2928
--------------------
2930
:Capability: KVM_CAP_ONE_REG
2931
:Architectures: all
2932
:Type: vcpu ioctl
2933
:Parameters: struct kvm_one_reg (in and out)
2934
:Returns: 0 on success, negative value on failure
2936
Errors include:
2938
======== ============================================================
2939
ENOENT no such register
2940
EINVAL invalid register ID, or no such register or used with VMs in
2941
protected virtualization mode on s390
2942
EPERM (arm64) register access not allowed before vcpu finalization
2943
======== ============================================================
2945
(These error codes are indicative only: do not rely on a specific error
2946
code being returned in a specific situation.)
2948
This ioctl allows to receive the value of a single register implemented
2949
in a vcpu. The register to read is indicated by the "id" field of the
2950
kvm_one_reg struct passed in. On success, the register value can be found
2951
at the memory location pointed to by "addr".
2953
The list of registers accessible using this interface is identical to the
2954
list in 4.68.
2957
4.70 KVM_KVMCLOCK_CTRL
2958
----------------------
2960
:Capability: KVM_CAP_KVMCLOCK_CTRL
2961
:Architectures: Any that implement pvclocks (currently x86 only)
2962
:Type: vcpu ioctl
2963
:Parameters: None
2964
:Returns: 0 on success, -1 on error
2966
This ioctl sets a flag accessible to the guest indicating that the specified
2967
vCPU has been paused by the host userspace.
2969
The host will set a flag in the pvclock structure that is checked from the
2970
soft lockup watchdog. The flag is part of the pvclock structure that is
2971
shared between guest and host, specifically the second bit of the flags
2972
field of the pvclock_vcpu_time_info structure. It will be set exclusively by
2973
the host and read/cleared exclusively by the guest. The guest operation of
2974
checking and clearing the flag must be an atomic operation so
2975
load-link/store-conditional, or equivalent must be used. There are two cases
2976
where the guest will clear the flag: when the soft lockup watchdog timer resets
2977
itself or when a soft lockup is detected. This ioctl can be called any time
2978
after pausing the vcpu, but before it is resumed.
2981
4.71 KVM_SIGNAL_MSI
2982
-------------------
2984
:Capability: KVM_CAP_SIGNAL_MSI
2985
:Architectures: x86 arm64
2986
:Type: vm ioctl
2987
:Parameters: struct kvm_msi (in)
2988
:Returns: >0 on delivery, 0 if guest blocked the MSI, and -1 on error
2990
Directly inject a MSI message. Only valid with in-kernel irqchip that handles
2991
MSI messages.
2993
::
2995
struct kvm_msi {
2996
__u32 address_lo;
2997
__u32 address_hi;
2998
__u32 data;
2999
__u32 flags;
3000
__u32 devid;
3001
__u8 pad[12];
3002
};
3004
flags:
3005
KVM_MSI_VALID_DEVID: devid contains a valid value. The per-VM
3006
KVM_CAP_MSI_DEVID capability advertises the requirement to provide
3007
the device ID. If this capability is not available, userspace
3008
should never set the KVM_MSI_VALID_DEVID flag as the ioctl might fail.
3010
If KVM_MSI_VALID_DEVID is set, devid contains a unique device identifier
3011
for the device that wrote the MSI message. For PCI, this is usually a
3012
BDF identifier in the lower 16 bits.
3014
On x86, address_hi is ignored unless the KVM_X2APIC_API_USE_32BIT_IDS
3015
feature of KVM_CAP_X2APIC_API capability is enabled. If it is enabled,
3016
address_hi bits 31-8 provide bits 31-8 of the destination id. Bits 7-0 of
3017
address_hi must be zero.
3020
4.71 KVM_CREATE_PIT2
3021
--------------------
3023
:Capability: KVM_CAP_PIT2
3024
:Architectures: x86
3025
:Type: vm ioctl
3026
:Parameters: struct kvm_pit_config (in)
3027
:Returns: 0 on success, -1 on error
3029
Creates an in-kernel device model for the i8254 PIT. This call is only valid
3030
after enabling in-kernel irqchip support via KVM_CREATE_IRQCHIP. The following
3031
parameters have to be passed::
3033
struct kvm_pit_config {
3034
__u32 flags;
3035
__u32 pad[15];
3036
};
3038
Valid flags are::
3040
#define KVM_PIT_SPEAKER_DUMMY 1 /* emulate speaker port stub */
3042
PIT timer interrupts may use a per-VM kernel thread for injection. If it
3043
exists, this thread will have a name of the following pattern::
3045
kvm-pit/<owner-process-pid>
3047
When running a guest with elevated priorities, the scheduling parameters of
3048
this thread may have to be adjusted accordingly.
3050
This IOCTL replaces the obsolete KVM_CREATE_PIT.
3053
4.72 KVM_GET_PIT2
3054
-----------------
3056
:Capability: KVM_CAP_PIT_STATE2
3057
:Architectures: x86
3058
:Type: vm ioctl
3059
:Parameters: struct kvm_pit_state2 (out)
3060
:Returns: 0 on success, -1 on error
3062
Retrieves the state of the in-kernel PIT model. Only valid after
3063
KVM_CREATE_PIT2. The state is returned in the following structure::
3065
struct kvm_pit_state2 {
3066
struct kvm_pit_channel_state channels[3];
3067
__u32 flags;
3068
__u32 reserved[9];
3069
};
3071
Valid flags are::
3073
/* disable PIT in HPET legacy mode */
3074
#define KVM_PIT_FLAGS_HPET_LEGACY 0x00000001
3075
/* speaker port data bit enabled */
3076
#define KVM_PIT_FLAGS_SPEAKER_DATA_ON 0x00000002
3078
This IOCTL replaces the obsolete KVM_GET_PIT.
3081
4.73 KVM_SET_PIT2
3082
-----------------
3084
:Capability: KVM_CAP_PIT_STATE2
3085
:Architectures: x86
3086
:Type: vm ioctl
3087
:Parameters: struct kvm_pit_state2 (in)
3088
:Returns: 0 on success, -1 on error
3090
Sets the state of the in-kernel PIT model. Only valid after KVM_CREATE_PIT2.
3091
See KVM_GET_PIT2 for details on struct kvm_pit_state2.
3093
.. Tip::
3094
``KVM_SET_PIT2`` strictly adheres to the spec of Intel 8254 PIT. For example,
3095
a ``count`` value of 0 in ``struct kvm_pit_channel_state`` is interpreted as
3096
65536, which is the maximum count value. Refer to `Intel 8254 programmable
3097
interval timer <https://www.scs.stanford.edu/10wi-cs140/pintos/specs/8254.pdf>`_.
3099
This IOCTL replaces the obsolete KVM_SET_PIT.
3102
4.74 KVM_PPC_GET_SMMU_INFO
3103
--------------------------
3105
:Capability: KVM_CAP_PPC_GET_SMMU_INFO
3106
:Architectures: powerpc
3107
:Type: vm ioctl
3108
:Parameters: None
3109
:Returns: 0 on success, -1 on error
3111
This populates and returns a structure describing the features of
3112
the "Server" class MMU emulation supported by KVM.
3113
This can in turn be used by userspace to generate the appropriate
3114
device-tree properties for the guest operating system.
3116
The structure contains some global information, followed by an
3117
array of supported segment page sizes::
3119
struct kvm_ppc_smmu_info {
3120
__u64 flags;
3121
__u32 slb_size;
3122
__u32 pad;
3123
struct kvm_ppc_one_seg_page_size sps[KVM_PPC_PAGE_SIZES_MAX_SZ];
3124
};
3126
The supported flags are:
3128
- KVM_PPC_PAGE_SIZES_REAL:
3129
When that flag is set, guest page sizes must "fit" the backing
3130
store page sizes. When not set, any page size in the list can
3131
be used regardless of how they are backed by userspace.
3133
- KVM_PPC_1T_SEGMENTS
3134
The emulated MMU supports 1T segments in addition to the
3135
standard 256M ones.
3137
- KVM_PPC_NO_HASH
3138
This flag indicates that HPT guests are not supported by KVM,
3139
thus all guests must use radix MMU mode.
3141
The "slb_size" field indicates how many SLB entries are supported
3143
The "sps" array contains 8 entries indicating the supported base
3144
page sizes for a segment in increasing order. Each entry is defined
3145
as follow::
3147
struct kvm_ppc_one_seg_page_size {
3148
__u32 page_shift; /* Base page shift of segment (or 0) */
3149
__u32 slb_enc; /* SLB encoding for BookS */
3150
struct kvm_ppc_one_page_size enc[KVM_PPC_PAGE_SIZES_MAX_SZ];
3151
};
3153
An entry with a "page_shift" of 0 is unused. Because the array is
3154
organized in increasing order, a lookup can stop when encountering
3155
such an entry.
3157
The "slb_enc" field provides the encoding to use in the SLB for the
3158
page size. The bits are in positions such as the value can directly
3159
be OR'ed into the "vsid" argument of the slbmte instruction.
3161
The "enc" array is a list which for each of those segment base page
3162
size provides the list of supported actual page sizes (which can be
3163
only larger or equal to the base page size), along with the
3164
corresponding encoding in the hash PTE. Similarly, the array is
3165
8 entries sorted by increasing sizes and an entry with a "0" shift
3166
is an empty entry and a terminator::
3168
struct kvm_ppc_one_page_size {
3169
__u32 page_shift; /* Page shift (or 0) */
3170
__u32 pte_enc; /* Encoding in the HPTE (>>12) */
3171
};
3173
The "pte_enc" field provides a value that can OR'ed into the hash
3174
PTE's RPN field (ie, it needs to be shifted left by 12 to OR it
3175
into the hash PTE second double word).
3177
4.75 KVM_IRQFD
3178
--------------
3180
:Capability: KVM_CAP_IRQFD
3181
:Architectures: x86 s390 arm64
3182
:Type: vm ioctl
3183
:Parameters: struct kvm_irqfd (in)
3184
:Returns: 0 on success, -1 on error
3186
Allows setting an eventfd to directly trigger a guest interrupt.
3187
kvm_irqfd.fd specifies the file descriptor to use as the eventfd and
3188
kvm_irqfd.gsi specifies the irqchip pin toggled by this event. When
3189
an event is triggered on the eventfd, an interrupt is injected into
3190
the guest using the specified gsi pin. The irqfd is removed using
3191
the KVM_IRQFD_FLAG_DEASSIGN flag, specifying both kvm_irqfd.fd
3192
and kvm_irqfd.gsi.
3194
With KVM_CAP_IRQFD_RESAMPLE, KVM_IRQFD supports a de-assert and notify
3195
mechanism allowing emulation of level-triggered, irqfd-based
3196
interrupts. When KVM_IRQFD_FLAG_RESAMPLE is set the user must pass an
3197
additional eventfd in the kvm_irqfd.resamplefd field. When operating
3198
in resample mode, posting of an interrupt through kvm_irq.fd asserts
3199
the specified gsi in the irqchip. When the irqchip is resampled, such
3200
as from an EOI, the gsi is de-asserted and the user is notified via
3201
kvm_irqfd.resamplefd. It is the user's responsibility to re-queue
3202
the interrupt if the device making use of it still requires service.
3203
Note that closing the resamplefd is not sufficient to disable the
3204
irqfd. The KVM_IRQFD_FLAG_RESAMPLE is only necessary on assignment
3205
and need not be specified with KVM_IRQFD_FLAG_DEASSIGN.
3207
On arm64, gsi routing being supported, the following can happen:
3209
- in case no routing entry is associated to this gsi, injection fails
3210
- in case the gsi is associated to an irqchip routing entry,
3211
irqchip.pin + 32 corresponds to the injected SPI ID.
3212
- in case the gsi is associated to an MSI routing entry, the MSI
3213
message and device ID are translated into an LPI (support restricted
3214
to GICv3 ITS in-kernel emulation).
3216
4.76 KVM_PPC_ALLOCATE_HTAB
3217
--------------------------
3219
:Capability: KVM_CAP_PPC_ALLOC_HTAB
3220
:Architectures: powerpc
3221
:Type: vm ioctl
3222
:Parameters: Pointer to u32 containing hash table order (in/out)
3223
:Returns: 0 on success, -1 on error
3225
This requests the host kernel to allocate an MMU hash table for a
3226
guest using the PAPR paravirtualization interface. This only does
3227
anything if the kernel is configured to use the Book 3S HV style of
3228
virtualization. Otherwise the capability doesn't exist and the ioctl
3229
returns an ENOTTY error. The rest of this description assumes Book 3S
3230
HV.
3232
There must be no vcpus running when this ioctl is called; if there
3233
are, it will do nothing and return an EBUSY error.
3235
The parameter is a pointer to a 32-bit unsigned integer variable
3236
containing the order (log base 2) of the desired size of the hash
3237
table, which must be between 18 and 46. On successful return from the
3238
ioctl, the value will not be changed by the kernel.
3240
If no hash table has been allocated when any vcpu is asked to run
3241
(with the KVM_RUN ioctl), the host kernel will allocate a
3242
default-sized hash table (16 MB).
3244
If this ioctl is called when a hash table has already been allocated,
3245
with a different order from the existing hash table, the existing hash
3246
table will be freed and a new one allocated. If this is ioctl is
3247
called when a hash table has already been allocated of the same order
3248
as specified, the kernel will clear out the existing hash table (zero
3249
all HPTEs). In either case, if the guest is using the virtualized
3250
real-mode area (VRMA) facility, the kernel will re-create the VMRA
3251
HPTEs on the next KVM_RUN of any vcpu.
3253
4.77 KVM_S390_INTERRUPT
3254
-----------------------
3256
:Capability: basic
3257
:Architectures: s390
3258
:Type: vm ioctl, vcpu ioctl
3259
:Parameters: struct kvm_s390_interrupt (in)
3260
:Returns: 0 on success, -1 on error
3262
Allows to inject an interrupt to the guest. Interrupts can be floating
3263
(vm ioctl) or per cpu (vcpu ioctl), depending on the interrupt type.
3265
Interrupt parameters are passed via kvm_s390_interrupt::
3267
struct kvm_s390_interrupt {
3268
__u32 type;
3269
__u32 parm;
3270
__u64 parm64;
3271
};
3273
type can be one of the following:
3275
KVM_S390_SIGP_STOP (vcpu)
3276
- sigp stop; optional flags in parm
3277
KVM_S390_PROGRAM_INT (vcpu)
3278
- program check; code in parm
3279
KVM_S390_SIGP_SET_PREFIX (vcpu)
3280
- sigp set prefix; prefix address in parm
3281
KVM_S390_RESTART (vcpu)
3282
- restart
3283
KVM_S390_INT_CLOCK_COMP (vcpu)
3284
- clock comparator interrupt
3285
KVM_S390_INT_CPU_TIMER (vcpu)
3286
- CPU timer interrupt
3287
KVM_S390_INT_VIRTIO (vm)
3288
- virtio external interrupt; external interrupt
3289
parameters in parm and parm64
3290
KVM_S390_INT_SERVICE (vm)
3291
- sclp external interrupt; sclp parameter in parm
3292
KVM_S390_INT_EMERGENCY (vcpu)
3293
- sigp emergency; source cpu in parm
3294
KVM_S390_INT_EXTERNAL_CALL (vcpu)
3295
- sigp external call; source cpu in parm
3296
KVM_S390_INT_IO(ai,cssid,ssid,schid) (vm)
3297
- compound value to indicate an
3298
I/O interrupt (ai - adapter interrupt; cssid,ssid,schid - subchannel);
3299
I/O interruption parameters in parm (subchannel) and parm64 (intparm,
3300
interruption subclass)
3301
KVM_S390_MCHK (vm, vcpu)
3302
- machine check interrupt; cr 14 bits in parm, machine check interrupt
3303
code in parm64 (note that machine checks needing further payload are not
3304
supported by this ioctl)
3306
This is an asynchronous vcpu ioctl and can be invoked from any thread.
3308
4.78 KVM_PPC_GET_HTAB_FD
3309
------------------------
3311
:Capability: KVM_CAP_PPC_HTAB_FD
3312
:Architectures: powerpc
3313
:Type: vm ioctl
3314
:Parameters: Pointer to struct kvm_get_htab_fd (in)
3315
:Returns: file descriptor number (>= 0) on success, -1 on error
3317
This returns a file descriptor that can be used either to read out the
3318
entries in the guest's hashed page table (HPT), or to write entries to
3319
initialize the HPT. The returned fd can only be written to if the
3320
KVM_GET_HTAB_WRITE bit is set in the flags field of the argument, and
3321
can only be read if that bit is clear. The argument struct looks like
3322
this::
3324
/* For KVM_PPC_GET_HTAB_FD */
3325
struct kvm_get_htab_fd {
3326
__u64 flags;
3327
__u64 start_index;
3328
__u64 reserved[2];
3329
};
3331
/* Values for kvm_get_htab_fd.flags */
3332
#define KVM_GET_HTAB_BOLTED_ONLY ((__u64)0x1)
3333
#define KVM_GET_HTAB_WRITE ((__u64)0x2)
3335
The 'start_index' field gives the index in the HPT of the entry at
3336
which to start reading. It is ignored when writing.
3338
Reads on the fd will initially supply information about all
3339
"interesting" HPT entries. Interesting entries are those with the
3340
bolted bit set, if the KVM_GET_HTAB_BOLTED_ONLY bit is set, otherwise
3341
all entries. When the end of the HPT is reached, the read() will
3342
return. If read() is called again on the fd, it will start again from
3343
the beginning of the HPT, but will only return HPT entries that have
3344
changed since they were last read.
3346
Data read or written is structured as a header (8 bytes) followed by a
3347
series of valid HPT entries (16 bytes) each. The header indicates how
3348
many valid HPT entries there are and how many invalid entries follow
3349
the valid entries. The invalid entries are not represented explicitly
3350
in the stream. The header format is::
3352
struct kvm_get_htab_header {
3353
__u32 index;
3354
__u16 n_valid;
3355
__u16 n_invalid;
3356
};
3358
Writes to the fd create HPT entries starting at the index given in the
3359
header; first 'n_valid' valid entries with contents from the data
3360
written, then 'n_invalid' invalid entries, invalidating any previously
3361
valid entries found.
3363
4.79 KVM_CREATE_DEVICE
3364
----------------------
3366
:Capability: KVM_CAP_DEVICE_CTRL
3367
:Architectures: all
3368
:Type: vm ioctl
3369
:Parameters: struct kvm_create_device (in/out)
3370
:Returns: 0 on success, -1 on error
3372
Errors:
3374
====== =======================================================
3375
ENODEV The device type is unknown or unsupported
3376
EEXIST Device already created, and this type of device may not
3377
be instantiated multiple times
3378
====== =======================================================
3380
Other error conditions may be defined by individual device types or
3381
have their standard meanings.
3383
Creates an emulated device in the kernel. The file descriptor returned
3384
in fd can be used with KVM_SET/GET/HAS_DEVICE_ATTR.
3386
If the KVM_CREATE_DEVICE_TEST flag is set, only test whether the
3387
device type is supported (not necessarily whether it can be created
3388
in the current vm).
3390
Individual devices should not define flags. Attributes should be used
3391
for specifying any behavior that is not implied by the device type
3392
number.
3394
::
3396
struct kvm_create_device {
3397
__u32 type; /* in: KVM_DEV_TYPE_xxx */
3398
__u32 fd; /* out: device handle */
3399
__u32 flags; /* in: KVM_CREATE_DEVICE_xxx */
3400
};
3402
4.80 KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR
3403
--------------------------------------------
3405
:Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device,
3406
KVM_CAP_VCPU_ATTRIBUTES for vcpu device
3407
KVM_CAP_SYS_ATTRIBUTES for system (/dev/kvm) device (no set)
3408
:Architectures: x86, arm64, s390
3409
:Type: device ioctl, vm ioctl, vcpu ioctl
3410
:Parameters: struct kvm_device_attr
3411
:Returns: 0 on success, -1 on error
3413
Errors:
3415
===== =============================================================
3416
ENXIO The group or attribute is unknown/unsupported for this device
3417
or hardware support is missing.
3418
EPERM The attribute cannot (currently) be accessed this way
3419
(e.g. read-only attribute, or attribute that only makes
3420
sense when the device is in a different state)
3421
===== =============================================================
3423
Other error conditions may be defined by individual device types.
3425
Gets/sets a specified piece of device configuration and/or state. The
3426
semantics are device-specific. See individual device documentation in
3427
the "devices" directory. As with ONE_REG, the size of the data
3428
transferred is defined by the particular attribute.
3430
::
3432
struct kvm_device_attr {
3433
__u32 flags; /* no flags currently defined */
3434
__u32 group; /* device-defined */
3435
__u64 attr; /* group-defined */
3436
__u64 addr; /* userspace address of attr data */
3437
};
3439
4.81 KVM_HAS_DEVICE_ATTR
3440
------------------------
3442
:Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device,
3443
KVM_CAP_VCPU_ATTRIBUTES for vcpu device
3444
KVM_CAP_SYS_ATTRIBUTES for system (/dev/kvm) device
3445
:Type: device ioctl, vm ioctl, vcpu ioctl
3446
:Parameters: struct kvm_device_attr
3447
:Returns: 0 on success, -1 on error
3449
Errors:
3451
===== =============================================================
3452
ENXIO The group or attribute is unknown/unsupported for this device
3453
or hardware support is missing.
3454
===== =============================================================
3456
Tests whether a device supports a particular attribute. A successful
3457
return indicates the attribute is implemented. It does not necessarily
3458
indicate that the attribute can be read or written in the device's
3459
current state. "addr" is ignored.
3461
.. _KVM_ARM_VCPU_INIT:
3463
4.82 KVM_ARM_VCPU_INIT
3464
----------------------
3466
:Capability: basic
3467
:Architectures: arm64
3468
:Type: vcpu ioctl
3469
:Parameters: struct kvm_vcpu_init (in)
3470
:Returns: 0 on success; -1 on error
3472
Errors:
3474
====== =================================================================
3475
EINVAL the target is unknown, or the combination of features is invalid.
3476
ENOENT a features bit specified is unknown.
3477
====== =================================================================
3479
This tells KVM what type of CPU to present to the guest, and what
3480
optional features it should have. This will cause a reset of the cpu
3481
registers to their initial values. If this is not called, KVM_RUN will
3482
return ENOEXEC for that vcpu.
3484
The initial values are defined as:
3485
- Processor state:
3486
* AArch64: EL1h, D, A, I and F bits set. All other bits
3487
are cleared.
3488
* AArch32: SVC, A, I and F bits set. All other bits are
3489
cleared.
3490
- General Purpose registers, including PC and SP: set to 0
3491
- FPSIMD/NEON registers: set to 0
3492
- SVE registers: set to 0
3493
- System registers: Reset to their architecturally defined
3494
values as for a warm reset to EL1 (resp. SVC) or EL2 (in the
3495
case of EL2 being enabled).
3497
Note that because some registers reflect machine topology, all vcpus
3498
should be created before this ioctl is invoked.
3500
Userspace can call this function multiple times for a given vcpu, including
3501
after the vcpu has been run. This will reset the vcpu to its initial
3502
state. All calls to this function after the initial call must use the same
3503
target and same set of feature flags, otherwise EINVAL will be returned.
3505
Possible features:
3507
- KVM_ARM_VCPU_POWER_OFF: Starts the CPU in a power-off state.
3508
Depends on KVM_CAP_ARM_PSCI. If not set, the CPU will be powered on
3509
and execute guest code when KVM_RUN is called.
3510
- KVM_ARM_VCPU_EL1_32BIT: Starts the CPU in a 32bit mode.
3511
Depends on KVM_CAP_ARM_EL1_32BIT (arm64 only).
3512
- KVM_ARM_VCPU_PSCI_0_2: Emulate PSCI v0.2 (or a future revision
3513
backward compatible with v0.2) for the CPU.
3514
Depends on KVM_CAP_ARM_PSCI_0_2.
3515
- KVM_ARM_VCPU_PMU_V3: Emulate PMUv3 for the CPU.
3516
Depends on KVM_CAP_ARM_PMU_V3.
3518
- KVM_ARM_VCPU_PTRAUTH_ADDRESS: Enables Address Pointer authentication
3519
for arm64 only.
3520
Depends on KVM_CAP_ARM_PTRAUTH_ADDRESS.
3521
If KVM_CAP_ARM_PTRAUTH_ADDRESS and KVM_CAP_ARM_PTRAUTH_GENERIC are
3522
both present, then both KVM_ARM_VCPU_PTRAUTH_ADDRESS and
3523
KVM_ARM_VCPU_PTRAUTH_GENERIC must be requested or neither must be
3524
requested.
3526
- KVM_ARM_VCPU_PTRAUTH_GENERIC: Enables Generic Pointer authentication
3527
for arm64 only.
3528
Depends on KVM_CAP_ARM_PTRAUTH_GENERIC.
3529
If KVM_CAP_ARM_PTRAUTH_ADDRESS and KVM_CAP_ARM_PTRAUTH_GENERIC are
3530
both present, then both KVM_ARM_VCPU_PTRAUTH_ADDRESS and
3531
KVM_ARM_VCPU_PTRAUTH_GENERIC must be requested or neither must be
3532
requested.
3534
- KVM_ARM_VCPU_SVE: Enables SVE for the CPU (arm64 only).
3535
Depends on KVM_CAP_ARM_SVE.
3536
Requires KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE):
3538
* After KVM_ARM_VCPU_INIT:
3540
- KVM_REG_ARM64_SVE_VLS may be read using KVM_GET_ONE_REG: the
3541
initial value of this pseudo-register indicates the best set of
3542
vector lengths possible for a vcpu on this host.
3544
* Before KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE):
3546
- KVM_RUN and KVM_GET_REG_LIST are not available;
3548
- KVM_GET_ONE_REG and KVM_SET_ONE_REG cannot be used to access
3549
the scalable architectural SVE registers
3550
KVM_REG_ARM64_SVE_ZREG(), KVM_REG_ARM64_SVE_PREG() or
3551
KVM_REG_ARM64_SVE_FFR;
3553
- KVM_REG_ARM64_SVE_VLS may optionally be written using
3554
KVM_SET_ONE_REG, to modify the set of vector lengths available
3555
for the vcpu.
3557
* After KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE):
3559
- the KVM_REG_ARM64_SVE_VLS pseudo-register is immutable, and can
3560
no longer be written using KVM_SET_ONE_REG.
3562
- KVM_ARM_VCPU_HAS_EL2: Enable Nested Virtualisation support,
3563
booting the guest from EL2 instead of EL1.
3564
Depends on KVM_CAP_ARM_EL2.
3565
The VM is running with HCR_EL2.E2H being RES1 (VHE) unless
3566
KVM_ARM_VCPU_HAS_EL2_E2H0 is also set.
3568
- KVM_ARM_VCPU_HAS_EL2_E2H0: Restrict Nested Virtualisation
3569
support to HCR_EL2.E2H being RES0 (non-VHE).
3570
Depends on KVM_CAP_ARM_EL2_E2H0.
3571
KVM_ARM_VCPU_HAS_EL2 must also be set.
3573
4.83 KVM_ARM_PREFERRED_TARGET
3574
-----------------------------
3576
:Capability: basic
3577
:Architectures: arm64
3578
:Type: vm ioctl
3579
:Parameters: struct kvm_vcpu_init (out)
3580
:Returns: 0 on success; -1 on error
3582
Errors:
3584
====== ==========================================
3585
ENODEV no preferred target available for the host
3586
====== ==========================================
3588
This queries KVM for preferred CPU target type which can be emulated
3589
by KVM on underlying host.
3591
The ioctl returns struct kvm_vcpu_init instance containing information
3592
about preferred CPU target type and recommended features for it. The
3593
kvm_vcpu_init->features bitmap returned will have feature bits set if
3594
the preferred target recommends setting these features, but this is
3595
not mandatory.
3597
The information returned by this ioctl can be used to prepare an instance
3598
of struct kvm_vcpu_init for KVM_ARM_VCPU_INIT ioctl which will result in
3599
VCPU matching underlying host.
3602
4.84 KVM_GET_REG_LIST
3603
---------------------
3605
:Capability: basic
3606
:Architectures: arm64, mips, riscv, x86 (if KVM_CAP_ONE_REG)
3607
:Type: vcpu ioctl
3608
:Parameters: struct kvm_reg_list (in/out)
3609
:Returns: 0 on success; -1 on error
3611
Errors:
3613
===== ==============================================================
3614
E2BIG the reg index list is too big to fit in the array specified by
3615
the user (the number required will be written into n).
3616
===== ==============================================================
3618
::
3620
struct kvm_reg_list {
3621
__u64 n; /* number of registers in reg[] */
3622
__u64 reg[0];
3623
};
3625
This ioctl returns the guest registers that are supported for the
3626
KVM_GET_ONE_REG/KVM_SET_ONE_REG calls.
3628
Note that s390 does not support KVM_GET_REG_LIST for historical reasons
3629
(read: nobody cared). The set of registers in kernels 4.x and newer is:
3631
- KVM_REG_S390_TODPR
3633
- KVM_REG_S390_EPOCHDIFF
3635
- KVM_REG_S390_CPU_TIMER
3637
- KVM_REG_S390_CLOCK_COMP
3639
- KVM_REG_S390_PFTOKEN
3641
- KVM_REG_S390_PFCOMPARE
3643
- KVM_REG_S390_PFSELECT
3645
- KVM_REG_S390_PP
3647
- KVM_REG_S390_GBEA
3649
Note, for x86, all MSRs enumerated by KVM_GET_MSR_INDEX_LIST are supported as
3650
type KVM_X86_REG_TYPE_MSR, but are NOT enumerated via KVM_GET_REG_LIST.
3652
4.85 KVM_ARM_SET_DEVICE_ADDR (deprecated)
3653
-----------------------------------------
3655
:Capability: KVM_CAP_ARM_SET_DEVICE_ADDR
3656
:Architectures: arm64
3657
:Type: vm ioctl
3658
:Parameters: struct kvm_arm_device_address (in)
3659
:Returns: 0 on success, -1 on error
3661
Errors:
3663
====== ============================================
3664
ENODEV The device id is unknown
3665
ENXIO Device not supported on current system
3666
EEXIST Address already set
3667
E2BIG Address outside guest physical address space
3668
EBUSY Address overlaps with other device range
3669
====== ============================================
3671
::
3673
struct kvm_arm_device_addr {
3674
__u64 id;
3675
__u64 addr;
3676
};
3678
Specify a device address in the guest's physical address space where guests
3679
can access emulated or directly exposed devices, which the host kernel needs
3680
to know about. The id field is an architecture specific identifier for a
3681
specific device.
3683
arm64 divides the id field into two parts, a device id and an
3684
address type id specific to the individual device::
3686
bits: | 63 ... 32 | 31 ... 16 | 15 ... 0 |
3687
field: | 0x00000000 | device id | addr type id |
3689
arm64 currently only require this when using the in-kernel GIC
3690
support for the hardware VGIC features, using KVM_ARM_DEVICE_VGIC_V2
3691
as the device id. When setting the base address for the guest's
3692
mapping of the VGIC virtual CPU and distributor interface, the ioctl
3693
must be called after calling KVM_CREATE_IRQCHIP, but before calling
3694
KVM_RUN on any of the VCPUs. Calling this ioctl twice for any of the
3695
base addresses will return -EEXIST.
3697
Note, this IOCTL is deprecated and the more flexible SET/GET_DEVICE_ATTR API
3698
should be used instead.
3701
4.86 KVM_PPC_RTAS_DEFINE_TOKEN
3702
------------------------------
3704
:Capability: KVM_CAP_PPC_RTAS
3705
:Architectures: ppc
3706
:Type: vm ioctl
3707
:Parameters: struct kvm_rtas_token_args
3708
:Returns: 0 on success, -1 on error
3710
Defines a token value for a RTAS (Run Time Abstraction Services)
3711
service in order to allow it to be handled in the kernel. The
3712
argument struct gives the name of the service, which must be the name
3713
of a service that has a kernel-side implementation. If the token
3714
value is non-zero, it will be associated with that service, and
3715
subsequent RTAS calls by the guest specifying that token will be
3716
handled by the kernel. If the token value is 0, then any token
3717
associated with the service will be forgotten, and subsequent RTAS
3718
calls by the guest for that service will be passed to userspace to be
3719
handled.
3721
4.87 KVM_SET_GUEST_DEBUG
3722
------------------------
3724
:Capability: KVM_CAP_SET_GUEST_DEBUG
3725
:Architectures: x86, s390, ppc, arm64
3726
:Type: vcpu ioctl
3727
:Parameters: struct kvm_guest_debug (in)
3728
:Returns: 0 on success; -1 on error
3730
::
3732
struct kvm_guest_debug {
3733
__u32 control;
3734
__u32 pad;
3735
struct kvm_guest_debug_arch arch;
3736
};
3738
Set up the processor specific debug registers and configure vcpu for
3739
handling guest debug events. There are two parts to the structure, the
3740
first a control bitfield indicates the type of debug events to handle
3741
when running. Common control bits are:
3743
- KVM_GUESTDBG_ENABLE: guest debugging is enabled
3744
- KVM_GUESTDBG_SINGLESTEP: the next run should single-step
3746
The top 16 bits of the control field are architecture specific control
3747
flags which can include the following:
3749
- KVM_GUESTDBG_USE_SW_BP: using software breakpoints [x86, arm64]
3750
- KVM_GUESTDBG_USE_HW_BP: using hardware breakpoints [x86, s390]
3751
- KVM_GUESTDBG_USE_HW: using hardware debug events [arm64]
3752
- KVM_GUESTDBG_INJECT_DB: inject DB type exception [x86]
3753
- KVM_GUESTDBG_INJECT_BP: inject BP type exception [x86]
3754
- KVM_GUESTDBG_EXIT_PENDING: trigger an immediate guest exit [s390]
3755
- KVM_GUESTDBG_BLOCKIRQ: avoid injecting interrupts/NMI/SMI [x86]
3757
For example KVM_GUESTDBG_USE_SW_BP indicates that software breakpoints
3758
are enabled in memory so we need to ensure breakpoint exceptions are
3759
correctly trapped and the KVM run loop exits at the breakpoint and not
3760
running off into the normal guest vector. For KVM_GUESTDBG_USE_HW_BP
3761
we need to ensure the guest vCPUs architecture specific registers are
3762
updated to the correct (supplied) values.
3764
The second part of the structure is architecture specific and
3765
typically contains a set of debug registers.
3767
For arm64 the number of debug registers is implementation defined and
3768
can be determined by querying the KVM_CAP_GUEST_DEBUG_HW_BPS and
3769
KVM_CAP_GUEST_DEBUG_HW_WPS capabilities which return a positive number
3770
indicating the number of supported registers.
3772
For ppc, the KVM_CAP_PPC_GUEST_DEBUG_SSTEP capability indicates whether
3773
the single-step debug event (KVM_GUESTDBG_SINGLESTEP) is supported.
3775
Also when supported, KVM_CAP_SET_GUEST_DEBUG2 capability indicates the
3776
supported KVM_GUESTDBG_* bits in the control field.
3778
When debug events exit the main run loop with the reason
3779
KVM_EXIT_DEBUG with the kvm_debug_exit_arch part of the kvm_run
3780
structure containing architecture specific debug information.
3782
4.88 KVM_GET_EMULATED_CPUID
3783
---------------------------
3785
:Capability: KVM_CAP_EXT_EMUL_CPUID
3786
:Architectures: x86
3787
:Type: system ioctl
3788
:Parameters: struct kvm_cpuid2 (in/out)
3789
:Returns: 0 on success, -1 on error
3791
::
3793
struct kvm_cpuid2 {
3794
__u32 nent;
3795
__u32 flags;
3796
struct kvm_cpuid_entry2 entries[0];
3797
};
3799
The member 'flags' is used for passing flags from userspace.
3801
::
3803
#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0)
3804
#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1) /* deprecated */
3805
#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2) /* deprecated */
3807
struct kvm_cpuid_entry2 {
3808
__u32 function;
3809
__u32 index;
3810
__u32 flags;
3811
__u32 eax;
3812
__u32 ebx;
3813
__u32 ecx;
3814
__u32 edx;
3815
__u32 padding[3];
3816
};
3818
This ioctl returns x86 cpuid features which are emulated by
3819
kvm.Userspace can use the information returned by this ioctl to query
3820
which features are emulated by kvm instead of being present natively.
3822
Userspace invokes KVM_GET_EMULATED_CPUID by passing a kvm_cpuid2
3823
structure with the 'nent' field indicating the number of entries in
3824
the variable-size array 'entries'. If the number of entries is too low
3825
to describe the cpu capabilities, an error (E2BIG) is returned. If the
3826
number is too high, the 'nent' field is adjusted and an error (ENOMEM)
3827
is returned. If the number is just right, the 'nent' field is adjusted
3828
to the number of valid entries in the 'entries' array, which is then
3829
filled.
3831
The entries returned are the set CPUID bits of the respective features
3832
which kvm emulates, as returned by the CPUID instruction, with unknown
3833
or unsupported feature bits cleared.
3835
Features like x2apic, for example, may not be present in the host cpu
3836
but are exposed by kvm in KVM_GET_SUPPORTED_CPUID because they can be
3837
emulated efficiently and thus not included here.
3839
The fields in each entry are defined as follows:
3841
function:
3842
the eax value used to obtain the entry
3843
index:
3844
the ecx value used to obtain the entry (for entries that are
3845
affected by ecx)
3846
flags:
3847
an OR of zero or more of the following:
3849
KVM_CPUID_FLAG_SIGNIFCANT_INDEX:
3850
if the index field is valid
3852
eax, ebx, ecx, edx:
3854
the values returned by the cpuid instruction for
3855
this function/index combination
3857
4.89 KVM_S390_MEM_OP
3858
--------------------
3860
:Capability: KVM_CAP_S390_MEM_OP, KVM_CAP_S390_PROTECTED, KVM_CAP_S390_MEM_OP_EXTENSION
3861
:Architectures: s390
3862
:Type: vm ioctl, vcpu ioctl
3863
:Parameters: struct kvm_s390_mem_op (in)
3864
:Returns: = 0 on success,
3865
< 0 on generic error (e.g. -EFAULT or -ENOMEM),
3866
16 bit program exception code if the access causes such an exception
3868
Read or write data from/to the VM's memory.
3869
The KVM_CAP_S390_MEM_OP_EXTENSION capability specifies what functionality is
3870
supported.
3872
Parameters are specified via the following structure::
3874
struct kvm_s390_mem_op {
3875
__u64 gaddr; /* the guest address */
3876
__u64 flags; /* flags */
3877
__u32 size; /* amount of bytes */
3878
__u32 op; /* type of operation */
3879
__u64 buf; /* buffer in userspace */
3880
union {
3881
struct {
3882
__u8 ar; /* the access register number */
3883
__u8 key; /* access key, ignored if flag unset */
3884
__u8 pad1[6]; /* ignored */
3885
__u64 old_addr; /* ignored if flag unset */
3886
};
3887
__u32 sida_offset; /* offset into the sida */
3888
__u8 reserved[32]; /* ignored */
3889
};
3890
};
3892
The start address of the memory region has to be specified in the "gaddr"
3893
field, and the length of the region in the "size" field (which must not
3894
be 0). The maximum value for "size" can be obtained by checking the
3895
KVM_CAP_S390_MEM_OP capability. "buf" is the buffer supplied by the
3896
userspace application where the read data should be written to for
3897
a read access, or where the data that should be written is stored for
3898
a write access. The "reserved" field is meant for future extensions.
3899
Reserved and unused values are ignored. Future extension that add members must
3900
introduce new flags.
3902
The type of operation is specified in the "op" field. Flags modifying
3903
their behavior can be set in the "flags" field. Undefined flag bits must
3904
be set to 0.
3906
Possible operations are:
3907
* ``KVM_S390_MEMOP_LOGICAL_READ``
3908
* ``KVM_S390_MEMOP_LOGICAL_WRITE``
3909
* ``KVM_S390_MEMOP_ABSOLUTE_READ``
3910
* ``KVM_S390_MEMOP_ABSOLUTE_WRITE``
3911
* ``KVM_S390_MEMOP_SIDA_READ``
3912
* ``KVM_S390_MEMOP_SIDA_WRITE``
3913
* ``KVM_S390_MEMOP_ABSOLUTE_CMPXCHG``
3915
Logical read/write:
3916
^^^^^^^^^^^^^^^^^^^
3918
Access logical memory, i.e. translate the given guest address to an absolute
3919
address given the state of the VCPU and use the absolute address as target of
3920
the access. "ar" designates the access register number to be used; the valid
3921
range is 0..15.
3922
Logical accesses are permitted for the VCPU ioctl only.
3923
Logical accesses are permitted for non-protected guests only.
3925
Supported flags:
3926
* ``KVM_S390_MEMOP_F_CHECK_ONLY``
3927
* ``KVM_S390_MEMOP_F_INJECT_EXCEPTION``
3928
* ``KVM_S390_MEMOP_F_SKEY_PROTECTION``
3930
The KVM_S390_MEMOP_F_CHECK_ONLY flag can be set to check whether the
3931
corresponding memory access would cause an access exception; however,
3932
no actual access to the data in memory at the destination is performed.
3933
In this case, "buf" is unused and can be NULL.
3935
In case an access exception occurred during the access (or would occur
3936
in case of KVM_S390_MEMOP_F_CHECK_ONLY), the ioctl returns a positive
3937
error number indicating the type of exception. This exception is also
3938
raised directly at the corresponding VCPU if the flag
3939
KVM_S390_MEMOP_F_INJECT_EXCEPTION is set.
3940
On protection exceptions, unless specified otherwise, the injected
3941
translation-exception identifier (TEID) indicates suppression.
3943
If the KVM_S390_MEMOP_F_SKEY_PROTECTION flag is set, storage key
3944
protection is also in effect and may cause exceptions if accesses are
3945
prohibited given the access key designated by "key"; the valid range is 0..15.
3946
KVM_S390_MEMOP_F_SKEY_PROTECTION is available if KVM_CAP_S390_MEM_OP_EXTENSION
3947
is > 0.
3948
Since the accessed memory may span multiple pages and those pages might have
3949
different storage keys, it is possible that a protection exception occurs
3950
after memory has been modified. In this case, if the exception is injected,
3951
the TEID does not indicate suppression.
3953
Absolute read/write:
3954
^^^^^^^^^^^^^^^^^^^^
3956
Access absolute memory. This operation is intended to be used with the
3957
KVM_S390_MEMOP_F_SKEY_PROTECTION flag, to allow accessing memory and performing
3958
the checks required for storage key protection as one operation (as opposed to
3959
user space getting the storage keys, performing the checks, and accessing
3960
memory thereafter, which could lead to a delay between check and access).
3961
Absolute accesses are permitted for the VM ioctl if KVM_CAP_S390_MEM_OP_EXTENSION
3962
has the KVM_S390_MEMOP_EXTENSION_CAP_BASE bit set.
3963
Currently absolute accesses are not permitted for VCPU ioctls.
3964
Absolute accesses are permitted for non-protected guests only.
3966
Supported flags:
3967
* ``KVM_S390_MEMOP_F_CHECK_ONLY``
3968
* ``KVM_S390_MEMOP_F_SKEY_PROTECTION``
3970
The semantics of the flags common with logical accesses are as for logical
3971
accesses.
3973
Absolute cmpxchg:
3974
^^^^^^^^^^^^^^^^^
3976
Perform cmpxchg on absolute guest memory. Intended for use with the
3977
KVM_S390_MEMOP_F_SKEY_PROTECTION flag.
3978
Instead of doing an unconditional write, the access occurs only if the target
3979
location contains the value pointed to by "old_addr".
3980
This is performed as an atomic cmpxchg with the length specified by the "size"
3981
parameter. "size" must be a power of two up to and including 16.
3982
If the exchange did not take place because the target value doesn't match the
3983
old value, the value "old_addr" points to is replaced by the target value.
3984
User space can tell if an exchange took place by checking if this replacement
3985
occurred. The cmpxchg op is permitted for the VM ioctl if
3986
KVM_CAP_S390_MEM_OP_EXTENSION has flag KVM_S390_MEMOP_EXTENSION_CAP_CMPXCHG set.
3988
Supported flags:
3989
* ``KVM_S390_MEMOP_F_SKEY_PROTECTION``
3991
SIDA read/write:
3992
^^^^^^^^^^^^^^^^
3994
Access the secure instruction data area which contains memory operands necessary
3995
for instruction emulation for protected guests.
3996
SIDA accesses are available if the KVM_CAP_S390_PROTECTED capability is available.
3997
SIDA accesses are permitted for the VCPU ioctl only.
3998
SIDA accesses are permitted for protected guests only.
4000
No flags are supported.
4002
4.90 KVM_S390_GET_SKEYS
4003
-----------------------
4005
:Capability: KVM_CAP_S390_SKEYS
4006
:Architectures: s390
4007
:Type: vm ioctl
4008
:Parameters: struct kvm_s390_skeys
4009
:Returns: 0 on success, KVM_S390_GET_SKEYS_NONE if guest is not using storage
4010
keys, negative value on error
4012
This ioctl is used to get guest storage key values on the s390
4013
architecture. The ioctl takes parameters via the kvm_s390_skeys struct::
4015
struct kvm_s390_skeys {
4016
__u64 start_gfn;
4017
__u64 count;
4018
__u64 skeydata_addr;
4019
__u32 flags;
4020
__u32 reserved[9];
4021
};
4023
The start_gfn field is the number of the first guest frame whose storage keys
4024
you want to get.
4026
The count field is the number of consecutive frames (starting from start_gfn)
4027
whose storage keys to get. The count field must be at least 1 and the maximum
4028
allowed value is defined as KVM_S390_SKEYS_MAX. Values outside this range
4029
will cause the ioctl to return -EINVAL.
4031
The skeydata_addr field is the address to a buffer large enough to hold count
4032
bytes. This buffer will be filled with storage key data by the ioctl.
4034
4.91 KVM_S390_SET_SKEYS
4035
-----------------------
4037
:Capability: KVM_CAP_S390_SKEYS
4038
:Architectures: s390
4039
:Type: vm ioctl
4040
:Parameters: struct kvm_s390_skeys
4041
:Returns: 0 on success, negative value on error
4043
This ioctl is used to set guest storage key values on the s390
4044
architecture. The ioctl takes parameters via the kvm_s390_skeys struct.
4045
See section on KVM_S390_GET_SKEYS for struct definition.
4047
The start_gfn field is the number of the first guest frame whose storage keys
4048
you want to set.
4050
The count field is the number of consecutive frames (starting from start_gfn)
4051
whose storage keys to get. The count field must be at least 1 and the maximum
4052
allowed value is defined as KVM_S390_SKEYS_MAX. Values outside this range
4053
will cause the ioctl to return -EINVAL.
4055
The skeydata_addr field is the address to a buffer containing count bytes of
4056
storage keys. Each byte in the buffer will be set as the storage key for a
4057
single frame starting at start_gfn for count frames.
4059
Note: If any architecturally invalid key value is found in the given data then
4060
the ioctl will return -EINVAL.
4062
4.92 KVM_S390_IRQ
4063
-----------------
4065
:Capability: KVM_CAP_S390_INJECT_IRQ
4066
:Architectures: s390
4067
:Type: vcpu ioctl
4068
:Parameters: struct kvm_s390_irq (in)
4069
:Returns: 0 on success, -1 on error
4071
Errors:
4074
====== =================================================================
4075
EINVAL interrupt type is invalid
4076
type is KVM_S390_SIGP_STOP and flag parameter is invalid value,
4077
type is KVM_S390_INT_EXTERNAL_CALL and code is bigger
4078
than the maximum of VCPUs
4079
EBUSY type is KVM_S390_SIGP_SET_PREFIX and vcpu is not stopped,
4080
type is KVM_S390_SIGP_STOP and a stop irq is already pending,
4081
type is KVM_S390_INT_EXTERNAL_CALL and an external call interrupt
4082
is already pending
4083
====== =================================================================
4085
Allows to inject an interrupt to the guest.
4087
Using struct kvm_s390_irq as a parameter allows
4088
to inject additional payload which is not
4089
possible via KVM_S390_INTERRUPT.
4091
Interrupt parameters are passed via kvm_s390_irq::
4093
struct kvm_s390_irq {
4094
__u64 type;
4095
union {
4096
struct kvm_s390_io_info io;
4097
struct kvm_s390_ext_info ext;
4098
struct kvm_s390_pgm_info pgm;
4099
struct kvm_s390_emerg_info emerg;
4100
struct kvm_s390_extcall_info extcall;
4101
struct kvm_s390_prefix_info prefix;
4102
struct kvm_s390_stop_info stop;
4103
struct kvm_s390_mchk_info mchk;
4104
char reserved[64];
4105
} u;
4106
};
4108
type can be one of the following:
4110
- KVM_S390_SIGP_STOP - sigp stop; parameter in .stop
4111
- KVM_S390_PROGRAM_INT - program check; parameters in .pgm
4112
- KVM_S390_SIGP_SET_PREFIX - sigp set prefix; parameters in .prefix
4113
- KVM_S390_RESTART - restart; no parameters
4114
- KVM_S390_INT_CLOCK_COMP - clock comparator interrupt; no parameters
4115
- KVM_S390_INT_CPU_TIMER - CPU timer interrupt; no parameters
4116
- KVM_S390_INT_EMERGENCY - sigp emergency; parameters in .emerg
4117
- KVM_S390_INT_EXTERNAL_CALL - sigp external call; parameters in .extcall
4118
- KVM_S390_MCHK - machine check interrupt; parameters in .mchk
4120
This is an asynchronous vcpu ioctl and can be invoked from any thread.
4122
4.94 KVM_S390_GET_IRQ_STATE
4123
---------------------------
4125
:Capability: KVM_CAP_S390_IRQ_STATE
4126
:Architectures: s390
4127
:Type: vcpu ioctl
4128
:Parameters: struct kvm_s390_irq_state (out)
4129
:Returns: >= number of bytes copied into buffer,
4130
-EINVAL if buffer size is 0,
4131
-ENOBUFS if buffer size is too small to fit all pending interrupts,
4132
-EFAULT if the buffer address was invalid
4134
This ioctl allows userspace to retrieve the complete state of all currently
4135
pending interrupts in a single buffer. Use cases include migration
4136
and introspection. The parameter structure contains the address of a
4137
userspace buffer and its length::
4139
struct kvm_s390_irq_state {
4140
__u64 buf;
4141
__u32 flags; /* will stay unused for compatibility reasons */
4142
__u32 len;
4143
__u32 reserved[4]; /* will stay unused for compatibility reasons */
4144
};
4146
Userspace passes in the above struct and for each pending interrupt a
4147
struct kvm_s390_irq is copied to the provided buffer.
4149
The structure contains a flags and a reserved field for future extensions. As
4150
the kernel never checked for flags == 0 and QEMU never pre-zeroed flags and
4151
reserved, these fields can not be used in the future without breaking
4152
compatibility.
4154
If -ENOBUFS is returned the buffer provided was too small and userspace
4155
may retry with a bigger buffer.
4157
4.95 KVM_S390_SET_IRQ_STATE
4158
---------------------------
4160
:Capability: KVM_CAP_S390_IRQ_STATE
4161
:Architectures: s390
4162
:Type: vcpu ioctl
4163
:Parameters: struct kvm_s390_irq_state (in)
4164
:Returns: 0 on success,
4165
-EFAULT if the buffer address was invalid,
4166
-EINVAL for an invalid buffer length (see below),
4167
-EBUSY if there were already interrupts pending,
4168
errors occurring when actually injecting the
4169
interrupt. See KVM_S390_IRQ.
4171
This ioctl allows userspace to set the complete state of all cpu-local
4172
interrupts currently pending for the vcpu. It is intended for restoring
4173
interrupt state after a migration. The input parameter is a userspace buffer
4174
containing a struct kvm_s390_irq_state::
4176
struct kvm_s390_irq_state {
4177
__u64 buf;
4178
__u32 flags; /* will stay unused for compatibility reasons */
4179
__u32 len;
4180
__u32 reserved[4]; /* will stay unused for compatibility reasons */
4181
};
4183
The restrictions for flags and reserved apply as well.
4184
(see KVM_S390_GET_IRQ_STATE)
4186
The userspace memory referenced by buf contains a struct kvm_s390_irq
4187
for each interrupt to be injected into the guest.
4188
If one of the interrupts could not be injected for some reason the
4189
ioctl aborts.
4191
len must be a multiple of sizeof(struct kvm_s390_irq). It must be > 0
4192
and it must not exceed (max_vcpus + 32) * sizeof(struct kvm_s390_irq),
4193
which is the maximum number of possibly pending cpu-local interrupts.
4195
4.96 KVM_SMI
4196
------------
4198
:Capability: KVM_CAP_X86_SMM
4199
:Architectures: x86
4200
:Type: vcpu ioctl
4201
:Parameters: none
4202
:Returns: 0 on success, -1 on error
4204
Queues an SMI on the thread's vcpu.
4206
4.97 KVM_X86_SET_MSR_FILTER
4207
----------------------------
4209
:Capability: KVM_CAP_X86_MSR_FILTER
4210
:Architectures: x86
4211
:Type: vm ioctl
4212
:Parameters: struct kvm_msr_filter
4213
:Returns: 0 on success, < 0 on error
4215
::
4217
struct kvm_msr_filter_range {
4218
#define KVM_MSR_FILTER_READ (1 << 0)
4219
#define KVM_MSR_FILTER_WRITE (1 << 1)
4220
__u32 flags;
4221
__u32 nmsrs; /* number of msrs in bitmap */
4222
__u32 base; /* MSR index the bitmap starts at */
4223
__u8 *bitmap; /* a 1 bit allows the operations in flags, 0 denies */
4224
};
4226
#define KVM_MSR_FILTER_MAX_RANGES 16
4227
struct kvm_msr_filter {
4228
#define KVM_MSR_FILTER_DEFAULT_ALLOW (0 << 0)
4229
#define KVM_MSR_FILTER_DEFAULT_DENY (1 << 0)
4230
__u32 flags;
4231
struct kvm_msr_filter_range ranges[KVM_MSR_FILTER_MAX_RANGES];
4232
};
4234
flags values for ``struct kvm_msr_filter_range``:
4236
``KVM_MSR_FILTER_READ``
4238
Filter read accesses to MSRs using the given bitmap. A 0 in the bitmap
4239
indicates that read accesses should be denied, while a 1 indicates that
4240
a read for a particular MSR should be allowed regardless of the default
4241
filter action.
4243
``KVM_MSR_FILTER_WRITE``
4245
Filter write accesses to MSRs using the given bitmap. A 0 in the bitmap
4246
indicates that write accesses should be denied, while a 1 indicates that
4247
a write for a particular MSR should be allowed regardless of the default
4248
filter action.
4250
flags values for ``struct kvm_msr_filter``:
4252
``KVM_MSR_FILTER_DEFAULT_ALLOW``
4254
If no filter range matches an MSR index that is getting accessed, KVM will
4255
allow accesses to all MSRs by default.
4257
``KVM_MSR_FILTER_DEFAULT_DENY``
4259
If no filter range matches an MSR index that is getting accessed, KVM will
4260
deny accesses to all MSRs by default.
4262
This ioctl allows userspace to define up to 16 bitmaps of MSR ranges to deny
4263
guest MSR accesses that would normally be allowed by KVM. If an MSR is not
4264
covered by a specific range, the "default" filtering behavior applies. Each
4265
bitmap range covers MSRs from [base .. base+nmsrs).
4267
If an MSR access is denied by userspace, the resulting KVM behavior depends on
4268
whether or not KVM_CAP_X86_USER_SPACE_MSR's KVM_MSR_EXIT_REASON_FILTER is
4269
enabled. If KVM_MSR_EXIT_REASON_FILTER is enabled, KVM will exit to userspace
4270
on denied accesses, i.e. userspace effectively intercepts the MSR access. If
4271
KVM_MSR_EXIT_REASON_FILTER is not enabled, KVM will inject a #GP into the guest
4272
on denied accesses. Note, if an MSR access is denied during emulation of MSR
4273
load/stores during VMX transitions, KVM ignores KVM_MSR_EXIT_REASON_FILTER.
4274
See the below warning for full details.
4276
If an MSR access is allowed by userspace, KVM will emulate and/or virtualize
4277
the access in accordance with the vCPU model. Note, KVM may still ultimately
4278
inject a #GP if an access is allowed by userspace, e.g. if KVM doesn't support
4279
the MSR, or to follow architectural behavior for the MSR.
4281
By default, KVM operates in KVM_MSR_FILTER_DEFAULT_ALLOW mode with no MSR range
4282
filters.
4284
Calling this ioctl with an empty set of ranges (all nmsrs == 0) disables MSR
4285
filtering. In that mode, ``KVM_MSR_FILTER_DEFAULT_DENY`` is invalid and causes
4286
an error.
4288
.. warning::
4289
MSR accesses that are side effects of instruction execution (emulated or
4290
native) are not filtered as hardware does not honor MSR bitmaps outside of
4291
RDMSR and WRMSR, and KVM mimics that behavior when emulating instructions
4292
to avoid pointless divergence from hardware. E.g. RDPID reads MSR_TSC_AUX,
4293
SYSENTER reads the SYSENTER MSRs, etc.
4295
MSRs that are loaded/stored via dedicated VMCS fields are not filtered as
4296
part of VM-Enter/VM-Exit emulation.
4298
MSRs that are loaded/store via VMX's load/store lists _are_ filtered as part
4299
of VM-Enter/VM-Exit emulation. If an MSR access is denied on VM-Enter, KVM
4300
synthesizes a consistency check VM-Exit(EXIT_REASON_MSR_LOAD_FAIL). If an
4301
MSR access is denied on VM-Exit, KVM synthesizes a VM-Abort. In short, KVM
4302
extends Intel's architectural list of MSRs that cannot be loaded/saved via
4303
the VM-Enter/VM-Exit MSR list. It is platform owner's responsibility to
4304
to communicate any such restrictions to their end users.
4306
x2APIC MSR accesses cannot be filtered (KVM silently ignores filters that
4307
cover any x2APIC MSRs).
4309
Note, invoking this ioctl while a vCPU is running is inherently racy. However,
4310
KVM does guarantee that vCPUs will see either the previous filter or the new
4311
filter, e.g. MSRs with identical settings in both the old and new filter will
4312
have deterministic behavior.
4314
Similarly, if userspace wishes to intercept on denied accesses,
4315
KVM_MSR_EXIT_REASON_FILTER must be enabled before activating any filters, and
4316
left enabled until after all filters are deactivated. Failure to do so may
4317
result in KVM injecting a #GP instead of exiting to userspace.
4319
4.98 KVM_CREATE_SPAPR_TCE_64
4320
----------------------------
4322
:Capability: KVM_CAP_SPAPR_TCE_64
4323
:Architectures: powerpc
4324
:Type: vm ioctl
4325
:Parameters: struct kvm_create_spapr_tce_64 (in)
4326
:Returns: file descriptor for manipulating the created TCE table
4328
This is an extension for KVM_CAP_SPAPR_TCE which only supports 32bit
4329
windows, described in 4.62 KVM_CREATE_SPAPR_TCE
4331
This capability uses extended struct in ioctl interface::
4333
/* for KVM_CAP_SPAPR_TCE_64 */
4334
struct kvm_create_spapr_tce_64 {
4335
__u64 liobn;
4336
__u32 page_shift;
4337
__u32 flags;
4338
__u64 offset; /* in pages */
4339
__u64 size; /* in pages */
4340
};
4342
The aim of extension is to support an additional bigger DMA window with
4343
a variable page size.
4344
KVM_CREATE_SPAPR_TCE_64 receives a 64bit window size, an IOMMU page shift and
4345
a bus offset of the corresponding DMA window, @size and @offset are numbers
4346
of IOMMU pages.
4348
@flags are not used at the moment.
4350
The rest of functionality is identical to KVM_CREATE_SPAPR_TCE.
4352
4.99 KVM_REINJECT_CONTROL
4353
-------------------------
4355
:Capability: KVM_CAP_REINJECT_CONTROL
4356
:Architectures: x86
4357
:Type: vm ioctl
4358
:Parameters: struct kvm_reinject_control (in)
4359
:Returns: 0 on success,
4360
-EFAULT if struct kvm_reinject_control cannot be read,
4361
-ENXIO if KVM_CREATE_PIT or KVM_CREATE_PIT2 didn't succeed earlier.
4363
i8254 (PIT) has two modes, reinject and !reinject. The default is reinject,
4364
where KVM queues elapsed i8254 ticks and monitors completion of interrupt from
4365
vector(s) that i8254 injects. Reinject mode dequeues a tick and injects its
4366
interrupt whenever there isn't a pending interrupt from i8254.
4367
!reinject mode injects an interrupt as soon as a tick arrives.
4369
::
4371
struct kvm_reinject_control {
4372
__u8 pit_reinject;
4373
__u8 reserved[31];
4374
};
4376
pit_reinject = 0 (!reinject mode) is recommended, unless running an old
4377
operating system that uses the PIT for timing (e.g. Linux 2.4.x).
4379
4.100 KVM_PPC_CONFIGURE_V3_MMU
4380
------------------------------
4382
:Capability: KVM_CAP_PPC_MMU_RADIX or KVM_CAP_PPC_MMU_HASH_V3
4383
:Architectures: ppc
4384
:Type: vm ioctl
4385
:Parameters: struct kvm_ppc_mmuv3_cfg (in)
4386
:Returns: 0 on success,
4387
-EFAULT if struct kvm_ppc_mmuv3_cfg cannot be read,
4388
-EINVAL if the configuration is invalid
4390
This ioctl controls whether the guest will use radix or HPT (hashed
4391
page table) translation, and sets the pointer to the process table for
4392
the guest.
4394
::
4396
struct kvm_ppc_mmuv3_cfg {
4397
__u64 flags;
4398
__u64 process_table;
4399
};
4401
There are two bits that can be set in flags; KVM_PPC_MMUV3_RADIX and
4402
KVM_PPC_MMUV3_GTSE. KVM_PPC_MMUV3_RADIX, if set, configures the guest
4403
to use radix tree translation, and if clear, to use HPT translation.
4404
KVM_PPC_MMUV3_GTSE, if set and if KVM permits it, configures the guest
4405
to be able to use the global TLB and SLB invalidation instructions;
4406
if clear, the guest may not use these instructions.
4408
The process_table field specifies the address and size of the guest
4409
process table, which is in the guest's space. This field is formatted
4410
as the second doubleword of the partition table entry, as defined in
4411
the Power ISA V3.00, Book III section 5.7.6.1.
4413
4.101 KVM_PPC_GET_RMMU_INFO
4414
---------------------------
4416
:Capability: KVM_CAP_PPC_MMU_RADIX
4417
:Architectures: ppc
4418
:Type: vm ioctl
4419
:Parameters: struct kvm_ppc_rmmu_info (out)
4420
:Returns: 0 on success,
4421
-EFAULT if struct kvm_ppc_rmmu_info cannot be written,
4422
-EINVAL if no useful information can be returned
4424
This ioctl returns a structure containing two things: (a) a list
4425
containing supported radix tree geometries, and (b) a list that maps
4426
page sizes to put in the "AP" (actual page size) field for the tlbie
4427
(TLB invalidate entry) instruction.
4429
::
4431
struct kvm_ppc_rmmu_info {
4432
struct kvm_ppc_radix_geom {
4433
__u8 page_shift;
4434
__u8 level_bits[4];
4435
__u8 pad[3];
4436
} geometries[8];
4437
__u32 ap_encodings[8];
4438
};
4440
The geometries[] field gives up to 8 supported geometries for the
4441
radix page table, in terms of the log base 2 of the smallest page
4442
size, and the number of bits indexed at each level of the tree, from
4443
the PTE level up to the PGD level in that order. Any unused entries
4444
will have 0 in the page_shift field.
4446
The ap_encodings gives the supported page sizes and their AP field
4447
encodings, encoded with the AP value in the top 3 bits and the log
4448
base 2 of the page size in the bottom 6 bits.
4450
4.102 KVM_PPC_RESIZE_HPT_PREPARE
4451
--------------------------------
4453
:Capability: KVM_CAP_SPAPR_RESIZE_HPT
4454
:Architectures: powerpc
4455
:Type: vm ioctl
4456
:Parameters: struct kvm_ppc_resize_hpt (in)
4457
:Returns: 0 on successful completion,
4458
>0 if a new HPT is being prepared, the value is an estimated
4459
number of milliseconds until preparation is complete,
4460
-EFAULT if struct kvm_reinject_control cannot be read,
4461
-EINVAL if the supplied shift or flags are invalid,
4462
-ENOMEM if unable to allocate the new HPT,
4464
Used to implement the PAPR extension for runtime resizing of a guest's
4465
Hashed Page Table (HPT). Specifically this starts, stops or monitors
4466
the preparation of a new potential HPT for the guest, essentially
4467
implementing the H_RESIZE_HPT_PREPARE hypercall.
4469
::
4471
struct kvm_ppc_resize_hpt {
4472
__u64 flags;
4473
__u32 shift;
4474
__u32 pad;
4475
};
4477
If called with shift > 0 when there is no pending HPT for the guest,
4478
this begins preparation of a new pending HPT of size 2^(shift) bytes.
4479
It then returns a positive integer with the estimated number of
4480
milliseconds until preparation is complete.
4482
If called when there is a pending HPT whose size does not match that
4483
requested in the parameters, discards the existing pending HPT and
4484
creates a new one as above.
4486
If called when there is a pending HPT of the size requested, will:
4488
* If preparation of the pending HPT is already complete, return 0
4489
* If preparation of the pending HPT has failed, return an error
4490
code, then discard the pending HPT.
4491
* If preparation of the pending HPT is still in progress, return an
4492
estimated number of milliseconds until preparation is complete.
4494
If called with shift == 0, discards any currently pending HPT and
4495
returns 0 (i.e. cancels any in-progress preparation).
4497
flags is reserved for future expansion, currently setting any bits in
4498
flags will result in an -EINVAL.
4500
Normally this will be called repeatedly with the same parameters until
4501
it returns <= 0. The first call will initiate preparation, subsequent
4502
ones will monitor preparation until it completes or fails.
4504
4.103 KVM_PPC_RESIZE_HPT_COMMIT
4505
-------------------------------
4507
:Capability: KVM_CAP_SPAPR_RESIZE_HPT
4508
:Architectures: powerpc
4509
:Type: vm ioctl
4510
:Parameters: struct kvm_ppc_resize_hpt (in)
4511
:Returns: 0 on successful completion,
4512
-EFAULT if struct kvm_reinject_control cannot be read,
4513
-EINVAL if the supplied shift or flags are invalid,
4514
-ENXIO is there is no pending HPT, or the pending HPT doesn't
4515
have the requested size,
4516
-EBUSY if the pending HPT is not fully prepared,
4517
-ENOSPC if there was a hash collision when moving existing
4518
HPT entries to the new HPT,
4519
-EIO on other error conditions
4521
Used to implement the PAPR extension for runtime resizing of a guest's
4522
Hashed Page Table (HPT). Specifically this requests that the guest be
4523
transferred to working with the new HPT, essentially implementing the
4524
H_RESIZE_HPT_COMMIT hypercall.
4526
::
4528
struct kvm_ppc_resize_hpt {
4529
__u64 flags;
4530
__u32 shift;
4531
__u32 pad;
4532
};
4534
This should only be called after KVM_PPC_RESIZE_HPT_PREPARE has
4535
returned 0 with the same parameters. In other cases
4536
KVM_PPC_RESIZE_HPT_COMMIT will return an error (usually -ENXIO or
4537
-EBUSY, though others may be possible if the preparation was started,
4538
but failed).
4540
This will have undefined effects on the guest if it has not already
4541
placed itself in a quiescent state where no vcpu will make MMU enabled
4542
memory accesses.
4544
On successful completion, the pending HPT will become the guest's active
4545
HPT and the previous HPT will be discarded.
4547
On failure, the guest will still be operating on its previous HPT.
4549
4.104 KVM_X86_GET_MCE_CAP_SUPPORTED
4550
-----------------------------------
4552
:Capability: KVM_CAP_MCE
4553
:Architectures: x86
4554
:Type: system ioctl
4555
:Parameters: u64 mce_cap (out)
4556
:Returns: 0 on success, -1 on error
4558
Returns supported MCE capabilities. The u64 mce_cap parameter
4559
has the same format as the MSR_IA32_MCG_CAP register. Supported
4560
capabilities will have the corresponding bits set.
4562
4.105 KVM_X86_SETUP_MCE
4563
-----------------------
4565
:Capability: KVM_CAP_MCE
4566
:Architectures: x86
4567
:Type: vcpu ioctl
4568
:Parameters: u64 mcg_cap (in)
4569
:Returns: 0 on success,
4570
-EFAULT if u64 mcg_cap cannot be read,
4571
-EINVAL if the requested number of banks is invalid,
4572
-EINVAL if requested MCE capability is not supported.
4574
Initializes MCE support for use. The u64 mcg_cap parameter
4575
has the same format as the MSR_IA32_MCG_CAP register and
4576
specifies which capabilities should be enabled. The maximum
4577
supported number of error-reporting banks can be retrieved when
4578
checking for KVM_CAP_MCE. The supported capabilities can be
4579
retrieved with KVM_X86_GET_MCE_CAP_SUPPORTED.
4581
4.106 KVM_X86_SET_MCE
4582
---------------------
4584
:Capability: KVM_CAP_MCE
4585
:Architectures: x86
4586
:Type: vcpu ioctl
4587
:Parameters: struct kvm_x86_mce (in)
4588
:Returns: 0 on success,
4589
-EFAULT if struct kvm_x86_mce cannot be read,
4590
-EINVAL if the bank number is invalid,
4591
-EINVAL if VAL bit is not set in status field.
4593
Inject a machine check error (MCE) into the guest. The input
4594
parameter is::
4596
struct kvm_x86_mce {
4597
__u64 status;
4598
__u64 addr;
4599
__u64 misc;
4600
__u64 mcg_status;
4601
__u8 bank;
4602
__u8 pad1[7];
4603
__u64 pad2[3];
4604
};
4606
If the MCE being reported is an uncorrected error, KVM will
4607
inject it as an MCE exception into the guest. If the guest
4608
MCG_STATUS register reports that an MCE is in progress, KVM
4609
causes an KVM_EXIT_SHUTDOWN vmexit.
4611
Otherwise, if the MCE is a corrected error, KVM will just
4612
store it in the corresponding bank (provided this bank is
4613
not holding a previously reported uncorrected error).
4615
4.107 KVM_S390_GET_CMMA_BITS
4616
----------------------------
4618
:Capability: KVM_CAP_S390_CMMA_MIGRATION
4619
:Architectures: s390
4620
:Type: vm ioctl
4621
:Parameters: struct kvm_s390_cmma_log (in, out)
4622
:Returns: 0 on success, a negative value on error
4624
Errors:
4626
====== =============================================================
4627
ENOMEM not enough memory can be allocated to complete the task
4628
ENXIO if CMMA is not enabled
4629
EINVAL if KVM_S390_CMMA_PEEK is not set but migration mode was not enabled
4630
EINVAL if KVM_S390_CMMA_PEEK is not set but dirty tracking has been
4631
disabled (and thus migration mode was automatically disabled)
4632
EFAULT if the userspace address is invalid or if no page table is
4633
present for the addresses (e.g. when using hugepages).
4634
====== =============================================================
4636
This ioctl is used to get the values of the CMMA bits on the s390
4637
architecture. It is meant to be used in two scenarios:
4639
- During live migration to save the CMMA values. Live migration needs
4640
to be enabled via the KVM_REQ_START_MIGRATION VM property.
4641
- To non-destructively peek at the CMMA values, with the flag
4642
KVM_S390_CMMA_PEEK set.
4644
The ioctl takes parameters via the kvm_s390_cmma_log struct. The desired
4645
values are written to a buffer whose location is indicated via the "values"
4646
member in the kvm_s390_cmma_log struct. The values in the input struct are
4647
also updated as needed.
4649
Each CMMA value takes up one byte.
4651
::
4653
struct kvm_s390_cmma_log {
4654
__u64 start_gfn;
4655
__u32 count;
4656
__u32 flags;
4657
union {
4658
__u64 remaining;
4659
__u64 mask;
4660
};
4661
__u64 values;
4662
};
4664
start_gfn is the number of the first guest frame whose CMMA values are
4665
to be retrieved,
4667
count is the length of the buffer in bytes,
4669
values points to the buffer where the result will be written to.
4671
If count is greater than KVM_S390_SKEYS_MAX, then it is considered to be
4672
KVM_S390_SKEYS_MAX. KVM_S390_SKEYS_MAX is re-used for consistency with
4673
other ioctls.
4675
The result is written in the buffer pointed to by the field values, and
4676
the values of the input parameter are updated as follows.
4678
Depending on the flags, different actions are performed. The only
4679
supported flag so far is KVM_S390_CMMA_PEEK.
4681
The default behaviour if KVM_S390_CMMA_PEEK is not set is:
4682
start_gfn will indicate the first page frame whose CMMA bits were dirty.
4683
It is not necessarily the same as the one passed as input, as clean pages
4684
are skipped.
4686
count will indicate the number of bytes actually written in the buffer.
4687
It can (and very often will) be smaller than the input value, since the
4688
buffer is only filled until 16 bytes of clean values are found (which
4689
are then not copied in the buffer). Since a CMMA migration block needs
4690
the base address and the length, for a total of 16 bytes, we will send
4691
back some clean data if there is some dirty data afterwards, as long as
4692
the size of the clean data does not exceed the size of the header. This
4693
allows to minimize the amount of data to be saved or transferred over
4694
the network at the expense of more roundtrips to userspace. The next
4695
invocation of the ioctl will skip over all the clean values, saving
4696
potentially more than just the 16 bytes we found.
4698
If KVM_S390_CMMA_PEEK is set:
4699
the existing storage attributes are read even when not in migration
4700
mode, and no other action is performed;
4702
the output start_gfn will be equal to the input start_gfn,
4704
the output count will be equal to the input count, except if the end of
4705
memory has been reached.
4707
In both cases:
4708
the field "remaining" will indicate the total number of dirty CMMA values
4709
still remaining, or 0 if KVM_S390_CMMA_PEEK is set and migration mode is
4710
not enabled.
4712
mask is unused.
4714
values points to the userspace buffer where the result will be stored.
4716
4.108 KVM_S390_SET_CMMA_BITS
4717
----------------------------
4719
:Capability: KVM_CAP_S390_CMMA_MIGRATION
4720
:Architectures: s390
4721
:Type: vm ioctl
4722
:Parameters: struct kvm_s390_cmma_log (in)
4723
:Returns: 0 on success, a negative value on error
4725
This ioctl is used to set the values of the CMMA bits on the s390
4726
architecture. It is meant to be used during live migration to restore
4727
the CMMA values, but there are no restrictions on its use.
4728
The ioctl takes parameters via the kvm_s390_cmma_values struct.
4729
Each CMMA value takes up one byte.
4731
::
4733
struct kvm_s390_cmma_log {
4734
__u64 start_gfn;
4735
__u32 count;
4736
__u32 flags;
4737
union {
4738
__u64 remaining;
4739
__u64 mask;
4740
};
4741
__u64 values;
4742
};
4744
start_gfn indicates the starting guest frame number,
4746
count indicates how many values are to be considered in the buffer,
4748
flags is not used and must be 0.
4750
mask indicates which PGSTE bits are to be considered.
4752
remaining is not used.
4754
values points to the buffer in userspace where to store the values.
4756
This ioctl can fail with -ENOMEM if not enough memory can be allocated to
4757
complete the task, with -ENXIO if CMMA is not enabled, with -EINVAL if
4758
the count field is too large (e.g. more than KVM_S390_CMMA_SIZE_MAX) or
4759
if the flags field was not 0, with -EFAULT if the userspace address is
4760
invalid, if invalid pages are written to (e.g. after the end of memory)
4761
or if no page table is present for the addresses (e.g. when using
4762
hugepages).
4764
4.109 KVM_PPC_GET_CPU_CHAR
4765
--------------------------
4767
:Capability: KVM_CAP_PPC_GET_CPU_CHAR
4768
:Architectures: powerpc
4769
:Type: vm ioctl
4770
:Parameters: struct kvm_ppc_cpu_char (out)
4771
:Returns: 0 on successful completion,
4772
-EFAULT if struct kvm_ppc_cpu_char cannot be written
4774
This ioctl gives userspace information about certain characteristics
4775
of the CPU relating to speculative execution of instructions and
4776
possible information leakage resulting from speculative execution (see
4777
CVE-2017-5715, CVE-2017-5753 and CVE-2017-5754). The information is
4778
returned in struct kvm_ppc_cpu_char, which looks like this::
4780
struct kvm_ppc_cpu_char {
4781
__u64 character; /* characteristics of the CPU */
4782
__u64 behaviour; /* recommended software behaviour */
4783
__u64 character_mask; /* valid bits in character */
4784
__u64 behaviour_mask; /* valid bits in behaviour */
4785
};
4787
For extensibility, the character_mask and behaviour_mask fields
4788
indicate which bits of character and behaviour have been filled in by
4789
the kernel. If the set of defined bits is extended in future then
4790
userspace will be able to tell whether it is running on a kernel that
4791
knows about the new bits.
4793
The character field describes attributes of the CPU which can help
4794
with preventing inadvertent information disclosure - specifically,
4795
whether there is an instruction to flash-invalidate the L1 data cache
4796
(ori 30,30,0 or mtspr SPRN_TRIG2,rN), whether the L1 data cache is set
4797
to a mode where entries can only be used by the thread that created
4798
them, whether the bcctr[l] instruction prevents speculation, and
4799
whether a speculation barrier instruction (ori 31,31,0) is provided.
4801
The behaviour field describes actions that software should take to
4802
prevent inadvertent information disclosure, and thus describes which
4803
vulnerabilities the hardware is subject to; specifically whether the
4804
L1 data cache should be flushed when returning to user mode from the
4805
kernel, and whether a speculation barrier should be placed between an
4806
array bounds check and the array access.
4808
These fields use the same bit definitions as the new
4809
H_GET_CPU_CHARACTERISTICS hypercall.
4811
4.110 KVM_MEMORY_ENCRYPT_OP
4812
---------------------------
4814
:Capability: basic
4815
:Architectures: x86
4816
:Type: vm ioctl, vcpu ioctl
4817
:Parameters: an opaque platform specific structure (in/out)
4818
:Returns: 0 on success; -1 on error
4820
If the platform supports creating encrypted VMs then this ioctl can be used
4821
for issuing platform-specific memory encryption commands to manage those
4822
encrypted VMs.
4824
Currently, this ioctl is used for issuing both Secure Encrypted Virtualization
4825
(SEV) commands on AMD Processors and Trusted Domain Extensions (TDX) commands
4826
on Intel Processors. The detailed commands are defined in
4827
Documentation/virt/kvm/x86/amd-memory-encryption.rst and
4828
Documentation/virt/kvm/x86/intel-tdx.rst.
4830
4.111 KVM_MEMORY_ENCRYPT_REG_REGION
4831
-----------------------------------
4833
:Capability: basic
4834
:Architectures: x86
4835
:Type: system
4836
:Parameters: struct kvm_enc_region (in)
4837
:Returns: 0 on success; -1 on error
4839
This ioctl can be used to register a guest memory region which may
4840
contain encrypted data (e.g. guest RAM, SMRAM etc).
4842
It is used in the SEV-enabled guest. When encryption is enabled, a guest
4843
memory region may contain encrypted data. The SEV memory encryption
4844
engine uses a tweak such that two identical plaintext pages, each at
4845
different locations will have differing ciphertexts. So swapping or
4846
moving ciphertext of those pages will not result in plaintext being
4847
swapped. So relocating (or migrating) physical backing pages for the SEV
4848
guest will require some additional steps.
4850
Note: The current SEV key management spec does not provide commands to
4851
swap or migrate (move) ciphertext pages. Hence, for now we pin the guest
4852
memory region registered with the ioctl.
4854
4.112 KVM_MEMORY_ENCRYPT_UNREG_REGION
4855
-------------------------------------
4857
:Capability: basic
4858
:Architectures: x86
4859
:Type: system
4860
:Parameters: struct kvm_enc_region (in)
4861
:Returns: 0 on success; -1 on error
4863
This ioctl can be used to unregister the guest memory region registered
4864
with KVM_MEMORY_ENCRYPT_REG_REGION ioctl above.
4866
4.113 KVM_HYPERV_EVENTFD
4867
------------------------
4869
:Capability: KVM_CAP_HYPERV_EVENTFD
4870
:Architectures: x86
4871
:Type: vm ioctl
4872
:Parameters: struct kvm_hyperv_eventfd (in)
4874
This ioctl (un)registers an eventfd to receive notifications from the guest on
4875
the specified Hyper-V connection id through the SIGNAL_EVENT hypercall, without
4876
causing a user exit. SIGNAL_EVENT hypercall with non-zero event flag number
4877
(bits 24-31) still triggers a KVM_EXIT_HYPERV_HCALL user exit.
4879
::
4881
struct kvm_hyperv_eventfd {
4882
__u32 conn_id;
4883
__s32 fd;
4884
__u32 flags;
4885
__u32 padding[3];
4886
};
4888
The conn_id field should fit within 24 bits::
4890
#define KVM_HYPERV_CONN_ID_MASK 0x00ffffff
4892
The acceptable values for the flags field are::
4894
#define KVM_HYPERV_EVENTFD_DEASSIGN (1 << 0)
4896
:Returns: 0 on success,
4897
-EINVAL if conn_id or flags is outside the allowed range,
4898
-ENOENT on deassign if the conn_id isn't registered,
4899
-EEXIST on assign if the conn_id is already registered
4901
4.114 KVM_GET_NESTED_STATE
4902
--------------------------
4904
:Capability: KVM_CAP_NESTED_STATE
4905
:Architectures: x86
4906
:Type: vcpu ioctl
4907
:Parameters: struct kvm_nested_state (in/out)
4908
:Returns: 0 on success, -1 on error
4910
Errors:
4912
===== =============================================================
4913
E2BIG the total state size exceeds the value of 'size' specified by
4914
the user; the size required will be written into size.
4915
===== =============================================================
4917
::
4919
struct kvm_nested_state {
4920
__u16 flags;
4921
__u16 format;
4922
__u32 size;
4924
union {
4925
struct kvm_vmx_nested_state_hdr vmx;
4926
struct kvm_svm_nested_state_hdr svm;
4928
/* Pad the header to 128 bytes. */
4929
__u8 pad[120];
4930
} hdr;
4932
union {
4933
struct kvm_vmx_nested_state_data vmx[0];
4934
struct kvm_svm_nested_state_data svm[0];
4935
} data;
4936
};
4938
#define KVM_STATE_NESTED_GUEST_MODE 0x00000001
4939
#define KVM_STATE_NESTED_RUN_PENDING 0x00000002
4940
#define KVM_STATE_NESTED_EVMCS 0x00000004
4942
#define KVM_STATE_NESTED_FORMAT_VMX 0
4943
#define KVM_STATE_NESTED_FORMAT_SVM 1
4945
#define KVM_STATE_NESTED_VMX_VMCS_SIZE 0x1000
4947
#define KVM_STATE_NESTED_VMX_SMM_GUEST_MODE 0x00000001
4948
#define KVM_STATE_NESTED_VMX_SMM_VMXON 0x00000002
4950
#define KVM_STATE_VMX_PREEMPTION_TIMER_DEADLINE 0x00000001
4952
struct kvm_vmx_nested_state_hdr {
4953
__u64 vmxon_pa;
4954
__u64 vmcs12_pa;
4956
struct {
4957
__u16 flags;
4958
} smm;
4960
__u32 flags;
4961
__u64 preemption_timer_deadline;
4962
};
4964
struct kvm_vmx_nested_state_data {
4965
__u8 vmcs12[KVM_STATE_NESTED_VMX_VMCS_SIZE];
4966
__u8 shadow_vmcs12[KVM_STATE_NESTED_VMX_VMCS_SIZE];
4967
};
4969
This ioctl copies the vcpu's nested virtualization state from the kernel to
4970
userspace.
4972
The maximum size of the state can be retrieved by passing KVM_CAP_NESTED_STATE
4973
to the KVM_CHECK_EXTENSION ioctl().
4975
4.115 KVM_SET_NESTED_STATE
4976
--------------------------
4978
:Capability: KVM_CAP_NESTED_STATE
4979
:Architectures: x86
4980
:Type: vcpu ioctl
4981
:Parameters: struct kvm_nested_state (in)
4982
:Returns: 0 on success, -1 on error
4984
This copies the vcpu's kvm_nested_state struct from userspace to the kernel.
4985
For the definition of struct kvm_nested_state, see KVM_GET_NESTED_STATE.
4987
4.116 KVM_(UN)REGISTER_COALESCED_MMIO
4988
-------------------------------------
4990
:Capability: KVM_CAP_COALESCED_MMIO (for coalesced mmio)
4991
KVM_CAP_COALESCED_PIO (for coalesced pio)
4992
:Architectures: all
4993
:Type: vm ioctl
4994
:Parameters: struct kvm_coalesced_mmio_zone
4995
:Returns: 0 on success, < 0 on error
4997
Coalesced I/O is a performance optimization that defers hardware
4998
register write emulation so that userspace exits are avoided. It is
4999
typically used to reduce the overhead of emulating frequently accessed
5000
hardware registers.
5002
When a hardware register is configured for coalesced I/O, write accesses
5003
do not exit to userspace and their value is recorded in a ring buffer
5004
that is shared between kernel and userspace.
5006
Coalesced I/O is used if one or more write accesses to a hardware
5007
register can be deferred until a read or a write to another hardware
5008
register on the same device. This last access will cause a vmexit and
5009
userspace will process accesses from the ring buffer before emulating
5010
it. That will avoid exiting to userspace on repeated writes.
5012
Coalesced pio is based on coalesced mmio. There is little difference
5013
between coalesced mmio and pio except that coalesced pio records accesses
5014
to I/O ports.
5016
4.117 KVM_CLEAR_DIRTY_LOG
5017
-------------------------
5019
:Capability: KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2
5020
:Architectures: x86, arm64, mips
5021
:Type: vm ioctl
5022
:Parameters: struct kvm_clear_dirty_log (in)
5023
:Returns: 0 on success, -1 on error
5025
::
5027
/* for KVM_CLEAR_DIRTY_LOG */
5028
struct kvm_clear_dirty_log {
5029
__u32 slot;
5030
__u32 num_pages;
5031
__u64 first_page;
5032
union {
5033
void __user *dirty_bitmap; /* one bit per page */
5034
__u64 padding;
5035
};
5036
};
5038
The ioctl clears the dirty status of pages in a memory slot, according to
5039
the bitmap that is passed in struct kvm_clear_dirty_log's dirty_bitmap
5040
field. Bit 0 of the bitmap corresponds to page "first_page" in the
5041
memory slot, and num_pages is the size in bits of the input bitmap.
5042
first_page must be a multiple of 64; num_pages must also be a multiple of
5043
64 unless first_page + num_pages is the size of the memory slot. For each
5044
bit that is set in the input bitmap, the corresponding page is marked "clean"
5045
in KVM's dirty bitmap, and dirty tracking is re-enabled for that page
5046
(for example via write-protection, or by clearing the dirty bit in
5047
a page table entry).
5049
If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 of slot field specifies
5050
the address space for which you want to clear the dirty status. See
5051
KVM_SET_USER_MEMORY_REGION for details on the usage of slot field.
5053
This ioctl is mostly useful when KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2
5054
is enabled; for more information, see the description of the capability.
5055
However, it can always be used as long as KVM_CHECK_EXTENSION confirms
5056
that KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 is present.
5058
4.118 KVM_GET_SUPPORTED_HV_CPUID
5059
--------------------------------
5061
:Capability: KVM_CAP_HYPERV_CPUID (vcpu), KVM_CAP_SYS_HYPERV_CPUID (system)
5062
:Architectures: x86
5063
:Type: system ioctl, vcpu ioctl
5064
:Parameters: struct kvm_cpuid2 (in/out)
5065
:Returns: 0 on success, -1 on error
5067
::
5069
struct kvm_cpuid2 {
5070
__u32 nent;
5071
__u32 padding;
5072
struct kvm_cpuid_entry2 entries[0];
5073
};
5075
struct kvm_cpuid_entry2 {
5076
__u32 function;
5077
__u32 index;
5078
__u32 flags;
5079
__u32 eax;
5080
__u32 ebx;
5081
__u32 ecx;
5082
__u32 edx;
5083
__u32 padding[3];
5084
};
5086
This ioctl returns x86 cpuid features leaves related to Hyper-V emulation in
5087
KVM. Userspace can use the information returned by this ioctl to construct
5088
cpuid information presented to guests consuming Hyper-V enlightenments (e.g.
5089
Windows or Hyper-V guests).
5091
CPUID feature leaves returned by this ioctl are defined by Hyper-V Top Level
5092
Functional Specification (TLFS). These leaves can't be obtained with
5093
KVM_GET_SUPPORTED_CPUID ioctl because some of them intersect with KVM feature
5094
leaves (0x40000000, 0x40000001).
5096
Currently, the following list of CPUID leaves are returned:
5098
- HYPERV_CPUID_VENDOR_AND_MAX_FUNCTIONS
5099
- HYPERV_CPUID_INTERFACE
5100
- HYPERV_CPUID_VERSION
5101
- HYPERV_CPUID_FEATURES
5102
- HYPERV_CPUID_ENLIGHTMENT_INFO
5103
- HYPERV_CPUID_IMPLEMENT_LIMITS
5104
- HYPERV_CPUID_NESTED_FEATURES
5105
- HYPERV_CPUID_SYNDBG_VENDOR_AND_MAX_FUNCTIONS
5106
- HYPERV_CPUID_SYNDBG_INTERFACE
5107
- HYPERV_CPUID_SYNDBG_PLATFORM_CAPABILITIES
5109
Userspace invokes KVM_GET_SUPPORTED_HV_CPUID by passing a kvm_cpuid2 structure
5110
with the 'nent' field indicating the number of entries in the variable-size
5111
array 'entries'. If the number of entries is too low to describe all Hyper-V
5112
feature leaves, an error (E2BIG) is returned. If the number is more or equal
5113
to the number of Hyper-V feature leaves, the 'nent' field is adjusted to the
5114
number of valid entries in the 'entries' array, which is then filled.
5116
'index' and 'flags' fields in 'struct kvm_cpuid_entry2' are currently reserved,
5117
userspace should not expect to get any particular value there.
5119
Note, vcpu version of KVM_GET_SUPPORTED_HV_CPUID is currently deprecated. Unlike
5120
system ioctl which exposes all supported feature bits unconditionally, vcpu
5121
version has the following quirks:
5123
- HYPERV_CPUID_NESTED_FEATURES leaf and HV_X64_ENLIGHTENED_VMCS_RECOMMENDED
5124
feature bit are only exposed when Enlightened VMCS was previously enabled
5125
on the corresponding vCPU (KVM_CAP_HYPERV_ENLIGHTENED_VMCS).
5126
- HV_STIMER_DIRECT_MODE_AVAILABLE bit is only exposed with in-kernel LAPIC.
5127
(presumes KVM_CREATE_IRQCHIP has already been called).
5129
4.119 KVM_ARM_VCPU_FINALIZE
5130
---------------------------
5132
:Architectures: arm64
5133
:Type: vcpu ioctl
5134
:Parameters: int feature (in)
5135
:Returns: 0 on success, -1 on error
5137
Errors:
5139
====== ==============================================================
5140
EPERM feature not enabled, needs configuration, or already finalized
5141
EINVAL feature unknown or not present
5142
====== ==============================================================
5144
Recognised values for feature:
5146
===== ===========================================
5147
arm64 KVM_ARM_VCPU_SVE (requires KVM_CAP_ARM_SVE)
5148
===== ===========================================
5150
Finalizes the configuration of the specified vcpu feature.
5152
The vcpu must already have been initialised, enabling the affected feature, by
5153
means of a successful :ref:`KVM_ARM_VCPU_INIT <KVM_ARM_VCPU_INIT>` call with the
5154
appropriate flag set in features[].
5156
For affected vcpu features, this is a mandatory step that must be performed
5157
before the vcpu is fully usable.
5159
Between KVM_ARM_VCPU_INIT and KVM_ARM_VCPU_FINALIZE, the feature may be
5160
configured by use of ioctls such as KVM_SET_ONE_REG. The exact configuration
5161
that should be performed and how to do it are feature-dependent.
5163
Other calls that depend on a particular feature being finalized, such as
5164
KVM_RUN, KVM_GET_REG_LIST, KVM_GET_ONE_REG and KVM_SET_ONE_REG, will fail with
5165
-EPERM unless the feature has already been finalized by means of a
5166
KVM_ARM_VCPU_FINALIZE call.
5168
See KVM_ARM_VCPU_INIT for details of vcpu features that require finalization
5169
using this ioctl.
5171
4.120 KVM_SET_PMU_EVENT_FILTER
5172
------------------------------
5174
:Capability: KVM_CAP_PMU_EVENT_FILTER
5175
:Architectures: x86
5176
:Type: vm ioctl
5177
:Parameters: struct kvm_pmu_event_filter (in)
5178
:Returns: 0 on success, -1 on error
5180
Errors:
5182
====== ============================================================
5183
EFAULT args[0] cannot be accessed
5184
EINVAL args[0] contains invalid data in the filter or filter events
5185
E2BIG nevents is too large
5186
EBUSY not enough memory to allocate the filter
5187
====== ============================================================
5189
::
5191
struct kvm_pmu_event_filter {
5192
__u32 action;
5193
__u32 nevents;
5194
__u32 fixed_counter_bitmap;
5195
__u32 flags;
5196
__u32 pad[4];
5197
__u64 events[0];
5198
};
5200
This ioctl restricts the set of PMU events the guest can program by limiting
5201
which event select and unit mask combinations are permitted.
5203
The argument holds a list of filter events which will be allowed or denied.
5205
Filter events only control general purpose counters; fixed purpose counters
5206
are controlled by the fixed_counter_bitmap.
5208
Valid values for 'flags'::
5210
``0``
5212
To use this mode, clear the 'flags' field.
5214
In this mode each event will contain an event select + unit mask.
5216
When the guest attempts to program the PMU the guest's event select +
5217
unit mask is compared against the filter events to determine whether the
5218
guest should have access.
5220
``KVM_PMU_EVENT_FLAG_MASKED_EVENTS``
5221
:Capability: KVM_CAP_PMU_EVENT_MASKED_EVENTS
5223
In this mode each filter event will contain an event select, mask, match, and
5224
exclude value. To encode a masked event use::
5226
KVM_PMU_ENCODE_MASKED_ENTRY()
5228
An encoded event will follow this layout::
5230
Bits Description
5231
---- -----------
5232
7:0 event select (low bits)
5233
15:8 umask match
5234
31:16 unused
5235
35:32 event select (high bits)
5236
36:54 unused
5237
55 exclude bit
5238
63:56 umask mask
5240
When the guest attempts to program the PMU, these steps are followed in
5241
determining if the guest should have access:
5243
1. Match the event select from the guest against the filter events.
5244
2. If a match is found, match the guest's unit mask to the mask and match
5245
values of the included filter events.
5246
I.e. (unit mask & mask) == match && !exclude.
5247
3. If a match is found, match the guest's unit mask to the mask and match
5248
values of the excluded filter events.
5249
I.e. (unit mask & mask) == match && exclude.
5250
4.
5251
a. If an included match is found and an excluded match is not found, filter
5252
the event.
5253
b. For everything else, do not filter the event.
5254
5.
5255
a. If the event is filtered and it's an allow list, allow the guest to
5256
program the event.
5257
b. If the event is filtered and it's a deny list, do not allow the guest to
5258
program the event.
5260
When setting a new pmu event filter, -EINVAL will be returned if any of the
5261
unused fields are set or if any of the high bits (35:32) in the event
5262
select are set when called on Intel.
5264
Valid values for 'action'::
5266
#define KVM_PMU_EVENT_ALLOW 0
5267
#define KVM_PMU_EVENT_DENY 1
5269
Via this API, KVM userspace can also control the behavior of the VM's fixed
5270
counters (if any) by configuring the "action" and "fixed_counter_bitmap" fields.
5272
Specifically, KVM follows the following pseudo-code when determining whether to
5273
allow the guest FixCtr[i] to count its pre-defined fixed event::
5275
FixCtr[i]_is_allowed = (action == ALLOW) && (bitmap & BIT(i)) ||
5276
(action == DENY) && !(bitmap & BIT(i));
5277
FixCtr[i]_is_denied = !FixCtr[i]_is_allowed;
5279
KVM always consumes fixed_counter_bitmap, it's userspace's responsibility to
5280
ensure fixed_counter_bitmap is set correctly, e.g. if userspace wants to define
5281
a filter that only affects general purpose counters.
5283
Note, the "events" field also applies to fixed counters' hardcoded event_select
5284
and unit_mask values. "fixed_counter_bitmap" has higher priority than "events"
5285
if there is a contradiction between the two.
5287
4.121 KVM_PPC_SVM_OFF
5288
---------------------
5290
:Capability: basic
5291
:Architectures: powerpc
5292
:Type: vm ioctl
5293
:Parameters: none
5294
:Returns: 0 on successful completion,
5296
Errors:
5298
====== ================================================================
5299
EINVAL if ultravisor failed to terminate the secure guest
5300
ENOMEM if hypervisor failed to allocate new radix page tables for guest
5301
====== ================================================================
5303
This ioctl is used to turn off the secure mode of the guest or transition
5304
the guest from secure mode to normal mode. This is invoked when the guest
5305
is reset. This has no effect if called for a normal guest.
5307
This ioctl issues an ultravisor call to terminate the secure guest,
5308
unpins the VPA pages and releases all the device pages that are used to
5309
track the secure pages by hypervisor.
5311
4.122 KVM_S390_NORMAL_RESET
5312
---------------------------
5314
:Capability: KVM_CAP_S390_VCPU_RESETS
5315
:Architectures: s390
5316
:Type: vcpu ioctl
5317
:Parameters: none
5318
:Returns: 0
5320
This ioctl resets VCPU registers and control structures according to
5321
the cpu reset definition in the POP (Principles Of Operation).
5323
4.123 KVM_S390_INITIAL_RESET
5324
----------------------------
5326
:Capability: basic
5327
:Architectures: s390
5328
:Type: vcpu ioctl
5329
:Parameters: none
5330
:Returns: 0
5332
This ioctl resets VCPU registers and control structures according to
5333
the initial cpu reset definition in the POP. However, the cpu is not
5334
put into ESA mode. This reset is a superset of the normal reset.
5336
4.124 KVM_S390_CLEAR_RESET
5337
--------------------------
5339
:Capability: KVM_CAP_S390_VCPU_RESETS
5340
:Architectures: s390
5341
:Type: vcpu ioctl
5342
:Parameters: none
5343
:Returns: 0
5345
This ioctl resets VCPU registers and control structures according to
5346
the clear cpu reset definition in the POP. However, the cpu is not put
5347
into ESA mode. This reset is a superset of the initial reset.
5350
4.125 KVM_S390_PV_COMMAND
5351
-------------------------
5353
:Capability: KVM_CAP_S390_PROTECTED
5354
:Architectures: s390
5355
:Type: vm ioctl
5356
:Parameters: struct kvm_pv_cmd
5357
:Returns: 0 on success, < 0 on error
5359
::
5361
struct kvm_pv_cmd {
5362
__u32 cmd; /* Command to be executed */
5363
__u16 rc; /* Ultravisor return code */
5364
__u16 rrc; /* Ultravisor return reason code */
5365
__u64 data; /* Data or address */
5366
__u32 flags; /* flags for future extensions. Must be 0 for now */
5367
__u32 reserved[3];
5368
};
5370
**Ultravisor return codes**
5371
The Ultravisor return (reason) codes are provided by the kernel if a
5372
Ultravisor call has been executed to achieve the results expected by
5373
the command. Therefore they are independent of the IOCTL return
5374
code. If KVM changes `rc`, its value will always be greater than 0
5375
hence setting it to 0 before issuing a PV command is advised to be
5376
able to detect a change of `rc`.
5378
**cmd values:**
5380
KVM_PV_ENABLE
5381
Allocate memory and register the VM with the Ultravisor, thereby
5382
donating memory to the Ultravisor that will become inaccessible to
5383
KVM. All existing CPUs are converted to protected ones. After this
5384
command has succeeded, any CPU added via hotplug will become
5385
protected during its creation as well.
5387
Errors:
5389
===== =============================
5390
EINTR an unmasked signal is pending
5391
===== =============================
5393
KVM_PV_DISABLE
5394
Deregister the VM from the Ultravisor and reclaim the memory that had
5395
been donated to the Ultravisor, making it usable by the kernel again.
5396
All registered VCPUs are converted back to non-protected ones. If a
5397
previous protected VM had been prepared for asynchronous teardown with
5398
KVM_PV_ASYNC_CLEANUP_PREPARE and not subsequently torn down with
5399
KVM_PV_ASYNC_CLEANUP_PERFORM, it will be torn down in this call
5400
together with the current protected VM.
5402
KVM_PV_VM_SET_SEC_PARMS
5403
Pass the image header from VM memory to the Ultravisor in
5404
preparation of image unpacking and verification.
5406
KVM_PV_VM_UNPACK
5407
Unpack (protect and decrypt) a page of the encrypted boot image.
5409
KVM_PV_VM_VERIFY
5410
Verify the integrity of the unpacked image. Only if this succeeds,
5411
KVM is allowed to start protected VCPUs.
5413
KVM_PV_INFO
5414
:Capability: KVM_CAP_S390_PROTECTED_DUMP
5416
Presents an API that provides Ultravisor related data to userspace
5417
via subcommands. len_max is the size of the user space buffer,
5418
len_written is KVM's indication of how much bytes of that buffer
5419
were actually written to. len_written can be used to determine the
5420
valid fields if more response fields are added in the future.
5422
::
5424
enum pv_cmd_info_id {
5425
KVM_PV_INFO_VM,
5426
KVM_PV_INFO_DUMP,
5427
};
5429
struct kvm_s390_pv_info_header {
5430
__u32 id;
5431
__u32 len_max;
5432
__u32 len_written;
5433
__u32 reserved;
5434
};
5436
struct kvm_s390_pv_info {
5437
struct kvm_s390_pv_info_header header;
5438
struct kvm_s390_pv_info_dump dump;
5439
struct kvm_s390_pv_info_vm vm;
5440
};
5442
**subcommands:**
5444
KVM_PV_INFO_VM
5445
This subcommand provides basic Ultravisor information for PV
5446
hosts. These values are likely also exported as files in the sysfs
5447
firmware UV query interface but they are more easily available to
5448
programs in this API.
5450
The installed calls and feature_indication members provide the
5451
installed UV calls and the UV's other feature indications.
5453
The max_* members provide information about the maximum number of PV
5454
vcpus, PV guests and PV guest memory size.
5456
::
5458
struct kvm_s390_pv_info_vm {
5459
__u64 inst_calls_list[4];
5460
__u64 max_cpus;
5461
__u64 max_guests;
5462
__u64 max_guest_addr;
5463
__u64 feature_indication;
5464
};
5467
KVM_PV_INFO_DUMP
5468
This subcommand provides information related to dumping PV guests.
5470
::
5472
struct kvm_s390_pv_info_dump {
5473
__u64 dump_cpu_buffer_len;
5474
__u64 dump_config_mem_buffer_per_1m;
5475
__u64 dump_config_finalize_len;
5476
};
5478
KVM_PV_DUMP
5479
:Capability: KVM_CAP_S390_PROTECTED_DUMP
5481
Presents an API that provides calls which facilitate dumping a
5482
protected VM.
5484
::
5486
struct kvm_s390_pv_dmp {
5487
__u64 subcmd;
5488
__u64 buff_addr;
5489
__u64 buff_len;
5490
__u64 gaddr; /* For dump storage state */
5491
};
5493
**subcommands:**
5495
KVM_PV_DUMP_INIT
5496
Initializes the dump process of a protected VM. If this call does
5497
not succeed all other subcommands will fail with -EINVAL. This
5498
subcommand will return -EINVAL if a dump process has not yet been
5499
completed.
5501
Not all PV vms can be dumped, the owner needs to set `dump
5502
allowed` PCF bit 34 in the SE header to allow dumping.
5504
KVM_PV_DUMP_CONFIG_STOR_STATE
5505
Stores `buff_len` bytes of tweak component values starting with
5506
the 1MB block specified by the absolute guest address
5507
(`gaddr`). `buff_len` needs to be `conf_dump_storage_state_len`
5508
aligned and at least >= the `conf_dump_storage_state_len` value
5509
provided by the dump uv_info data. buff_user might be written to
5510
even if an error rc is returned. For instance if we encounter a
5511
fault after writing the first page of data.
5513
KVM_PV_DUMP_COMPLETE
5514
If the subcommand succeeds it completes the dump process and lets
5515
KVM_PV_DUMP_INIT be called again.
5517
On success `conf_dump_finalize_len` bytes of completion data will be
5518
stored to the `buff_addr`. The completion data contains a key
5519
derivation seed, IV, tweak nonce and encryption keys as well as an
5520
authentication tag all of which are needed to decrypt the dump at a
5521
later time.
5523
KVM_PV_ASYNC_CLEANUP_PREPARE
5524
:Capability: KVM_CAP_S390_PROTECTED_ASYNC_DISABLE
5526
Prepare the current protected VM for asynchronous teardown. Most
5527
resources used by the current protected VM will be set aside for a
5528
subsequent asynchronous teardown. The current protected VM will then
5529
resume execution immediately as non-protected. There can be at most
5530
one protected VM prepared for asynchronous teardown at any time. If
5531
a protected VM had already been prepared for teardown without
5532
subsequently calling KVM_PV_ASYNC_CLEANUP_PERFORM, this call will
5533
fail. In that case, the userspace process should issue a normal
5534
KVM_PV_DISABLE. The resources set aside with this call will need to
5535
be cleaned up with a subsequent call to KVM_PV_ASYNC_CLEANUP_PERFORM
5536
or KVM_PV_DISABLE, otherwise they will be cleaned up when KVM
5537
terminates. KVM_PV_ASYNC_CLEANUP_PREPARE can be called again as soon
5538
as cleanup starts, i.e. before KVM_PV_ASYNC_CLEANUP_PERFORM finishes.
5540
KVM_PV_ASYNC_CLEANUP_PERFORM
5541
:Capability: KVM_CAP_S390_PROTECTED_ASYNC_DISABLE
5543
Tear down the protected VM previously prepared for teardown with
5544
KVM_PV_ASYNC_CLEANUP_PREPARE. The resources that had been set aside
5545
will be freed during the execution of this command. This PV command
5546
should ideally be issued by userspace from a separate thread. If a
5547
fatal signal is received (or the process terminates naturally), the
5548
command will terminate immediately without completing, and the normal
5549
KVM shutdown procedure will take care of cleaning up all remaining
5550
protected VMs, including the ones whose teardown was interrupted by
5551
process termination.
5553
4.126 KVM_XEN_HVM_SET_ATTR
5554
--------------------------
5556
:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO
5557
:Architectures: x86
5558
:Type: vm ioctl
5559
:Parameters: struct kvm_xen_hvm_attr
5560
:Returns: 0 on success, < 0 on error
5562
::
5564
struct kvm_xen_hvm_attr {
5565
__u16 type;
5566
__u16 pad[3];
5567
union {
5568
__u8 long_mode;
5569
__u8 vector;
5570
__u8 runstate_update_flag;
5571
union {
5572
__u64 gfn;
5573
__u64 hva;
5574
} shared_info;
5575
struct {
5576
__u32 send_port;
5577
__u32 type; /* EVTCHNSTAT_ipi / EVTCHNSTAT_interdomain */
5578
__u32 flags;
5579
union {
5580
struct {
5581
__u32 port;
5582
__u32 vcpu;
5583
__u32 priority;
5584
} port;
5585
struct {
5586
__u32 port; /* Zero for eventfd */
5587
__s32 fd;
5588
} eventfd;
5589
__u32 padding[4];
5590
} deliver;
5591
} evtchn;
5592
__u32 xen_version;
5593
__u64 pad[8];
5594
} u;
5595
};
5597
type values:
5599
KVM_XEN_ATTR_TYPE_LONG_MODE
5600
Sets the ABI mode of the VM to 32-bit or 64-bit (long mode). This
5601
determines the layout of the shared_info page exposed to the VM.
5603
KVM_XEN_ATTR_TYPE_SHARED_INFO
5604
Sets the guest physical frame number at which the Xen shared_info
5605
page resides. Note that although Xen places vcpu_info for the first
5606
32 vCPUs in the shared_info page, KVM does not automatically do so
5607
and instead requires that KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO or
5608
KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO_HVA be used explicitly even when
5609
the vcpu_info for a given vCPU resides at the "default" location
5610
in the shared_info page. This is because KVM may not be aware of
5611
the Xen CPU id which is used as the index into the vcpu_info[]
5612
array, so may know the correct default location.
5614
Note that the shared_info page may be constantly written to by KVM;
5615
it contains the event channel bitmap used to deliver interrupts to
5616
a Xen guest, amongst other things. It is exempt from dirty tracking
5617
mechanisms — KVM will not explicitly mark the page as dirty each
5618
time an event channel interrupt is delivered to the guest! Thus,
5619
userspace should always assume that the designated GFN is dirty if
5620
any vCPU has been running or any event channel interrupts can be
5621
routed to the guest.
5623
Setting the gfn to KVM_XEN_INVALID_GFN will disable the shared_info
5624
page.
5626
KVM_XEN_ATTR_TYPE_SHARED_INFO_HVA
5627
If the KVM_XEN_HVM_CONFIG_SHARED_INFO_HVA flag is also set in the
5628
Xen capabilities, then this attribute may be used to set the
5629
userspace address at which the shared_info page resides, which
5630
will always be fixed in the VMM regardless of where it is mapped
5631
in guest physical address space. This attribute should be used in
5632
preference to KVM_XEN_ATTR_TYPE_SHARED_INFO as it avoids
5633
unnecessary invalidation of an internal cache when the page is
5634
re-mapped in guest physical address space.
5636
Setting the hva to zero will disable the shared_info page.
5638
KVM_XEN_ATTR_TYPE_UPCALL_VECTOR
5639
Sets the exception vector used to deliver Xen event channel upcalls.
5640
This is the HVM-wide vector injected directly by the hypervisor
5641
(not through the local APIC), typically configured by a guest via
5642
HVM_PARAM_CALLBACK_IRQ. This can be disabled again (e.g. for guest
5643
SHUTDOWN_soft_reset) by setting it to zero.
5645
KVM_XEN_ATTR_TYPE_EVTCHN
5646
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates
5647
support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It configures
5648
an outbound port number for interception of EVTCHNOP_send requests
5649
from the guest. A given sending port number may be directed back to
5650
a specified vCPU (by APIC ID) / port / priority on the guest, or to
5651
trigger events on an eventfd. The vCPU and priority can be changed
5652
by setting KVM_XEN_EVTCHN_UPDATE in a subsequent call, but other
5653
fields cannot change for a given sending port. A port mapping is
5654
removed by using KVM_XEN_EVTCHN_DEASSIGN in the flags field. Passing
5655
KVM_XEN_EVTCHN_RESET in the flags field removes all interception of
5656
outbound event channels. The values of the flags field are mutually
5657
exclusive and cannot be combined as a bitmask.
5659
KVM_XEN_ATTR_TYPE_XEN_VERSION
5660
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates
5661
support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It configures
5662
the 32-bit version code returned to the guest when it invokes the
5663
XENVER_version call; typically (XEN_MAJOR << 16 | XEN_MINOR). PV
5664
Xen guests will often use this to as a dummy hypercall to trigger
5665
event channel delivery, so responding within the kernel without
5666
exiting to userspace is beneficial.
5668
KVM_XEN_ATTR_TYPE_RUNSTATE_UPDATE_FLAG
5669
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates
5670
support for KVM_XEN_HVM_CONFIG_RUNSTATE_UPDATE_FLAG. It enables the
5671
XEN_RUNSTATE_UPDATE flag which allows guest vCPUs to safely read
5672
other vCPUs' vcpu_runstate_info. Xen guests enable this feature via
5673
the VMASST_TYPE_runstate_update_flag of the HYPERVISOR_vm_assist
5674
hypercall.
5676
4.127 KVM_XEN_HVM_GET_ATTR
5677
--------------------------
5679
:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO
5680
:Architectures: x86
5681
:Type: vm ioctl
5682
:Parameters: struct kvm_xen_hvm_attr
5683
:Returns: 0 on success, < 0 on error
5685
Allows Xen VM attributes to be read. For the structure and types,
5686
see KVM_XEN_HVM_SET_ATTR above. The KVM_XEN_ATTR_TYPE_EVTCHN
5687
attribute cannot be read.
5689
4.128 KVM_XEN_VCPU_SET_ATTR
5690
---------------------------
5692
:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO
5693
:Architectures: x86
5694
:Type: vcpu ioctl
5695
:Parameters: struct kvm_xen_vcpu_attr
5696
:Returns: 0 on success, < 0 on error
5698
::
5700
struct kvm_xen_vcpu_attr {
5701
__u16 type;
5702
__u16 pad[3];
5703
union {
5704
__u64 gpa;
5705
__u64 pad[4];
5706
struct {
5707
__u64 state;
5708
__u64 state_entry_time;
5709
__u64 time_running;
5710
__u64 time_runnable;
5711
__u64 time_blocked;
5712
__u64 time_offline;
5713
} runstate;
5714
__u32 vcpu_id;
5715
struct {
5716
__u32 port;
5717
__u32 priority;
5718
__u64 expires_ns;
5719
} timer;
5720
__u8 vector;
5721
} u;
5722
};
5724
type values:
5726
KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO
5727
Sets the guest physical address of the vcpu_info for a given vCPU.
5728
As with the shared_info page for the VM, the corresponding page may be
5729
dirtied at any time if event channel interrupt delivery is enabled, so
5730
userspace should always assume that the page is dirty without relying
5731
on dirty logging. Setting the gpa to KVM_XEN_INVALID_GPA will disable
5732
the vcpu_info.
5734
KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO_HVA
5735
If the KVM_XEN_HVM_CONFIG_SHARED_INFO_HVA flag is also set in the
5736
Xen capabilities, then this attribute may be used to set the
5737
userspace address of the vcpu_info for a given vCPU. It should
5738
only be used when the vcpu_info resides at the "default" location
5739
in the shared_info page. In this case it is safe to assume the
5740
userspace address will not change, because the shared_info page is
5741
an overlay on guest memory and remains at a fixed host address
5742
regardless of where it is mapped in guest physical address space
5743
and hence unnecessary invalidation of an internal cache may be
5744
avoided if the guest memory layout is modified.
5745
If the vcpu_info does not reside at the "default" location then
5746
it is not guaranteed to remain at the same host address and
5747
hence the aforementioned cache invalidation is required.
5749
KVM_XEN_VCPU_ATTR_TYPE_VCPU_TIME_INFO
5750
Sets the guest physical address of an additional pvclock structure
5751
for a given vCPU. This is typically used for guest vsyscall support.
5752
Setting the gpa to KVM_XEN_INVALID_GPA will disable the structure.
5754
KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADDR
5755
Sets the guest physical address of the vcpu_runstate_info for a given
5756
vCPU. This is how a Xen guest tracks CPU state such as steal time.
5757
Setting the gpa to KVM_XEN_INVALID_GPA will disable the runstate area.
5759
KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_CURRENT
5760
Sets the runstate (RUNSTATE_running/_runnable/_blocked/_offline) of
5761
the given vCPU from the .u.runstate.state member of the structure.
5762
KVM automatically accounts running and runnable time but blocked
5763
and offline states are only entered explicitly.
5765
KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_DATA
5766
Sets all fields of the vCPU runstate data from the .u.runstate member
5767
of the structure, including the current runstate. The state_entry_time
5768
must equal the sum of the other four times.
5770
KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADJUST
5771
This *adds* the contents of the .u.runstate members of the structure
5772
to the corresponding members of the given vCPU's runstate data, thus
5773
permitting atomic adjustments to the runstate times. The adjustment
5774
to the state_entry_time must equal the sum of the adjustments to the
5775
other four times. The state field must be set to -1, or to a valid
5776
runstate value (RUNSTATE_running, RUNSTATE_runnable, RUNSTATE_blocked
5777
or RUNSTATE_offline) to set the current accounted state as of the
5778
adjusted state_entry_time.
5780
KVM_XEN_VCPU_ATTR_TYPE_VCPU_ID
5781
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates
5782
support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It sets the Xen
5783
vCPU ID of the given vCPU, to allow timer-related VCPU operations to
5784
be intercepted by KVM.
5786
KVM_XEN_VCPU_ATTR_TYPE_TIMER
5787
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates
5788
support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It sets the
5789
event channel port/priority for the VIRQ_TIMER of the vCPU, as well
5790
as allowing a pending timer to be saved/restored. Setting the timer
5791
port to zero disables kernel handling of the singleshot timer.
5793
KVM_XEN_VCPU_ATTR_TYPE_UPCALL_VECTOR
5794
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates
5795
support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It sets the
5796
per-vCPU local APIC upcall vector, configured by a Xen guest with
5797
the HVMOP_set_evtchn_upcall_vector hypercall. This is typically
5798
used by Windows guests, and is distinct from the HVM-wide upcall
5799
vector configured with HVM_PARAM_CALLBACK_IRQ. It is disabled by
5800
setting the vector to zero.
5803
4.129 KVM_XEN_VCPU_GET_ATTR
5804
---------------------------
5806
:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO
5807
:Architectures: x86
5808
:Type: vcpu ioctl
5809
:Parameters: struct kvm_xen_vcpu_attr
5810
:Returns: 0 on success, < 0 on error
5812
Allows Xen vCPU attributes to be read. For the structure and types,
5813
see KVM_XEN_VCPU_SET_ATTR above.
5815
The KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADJUST type may not be used
5816
with the KVM_XEN_VCPU_GET_ATTR ioctl.
5818
4.130 KVM_ARM_MTE_COPY_TAGS
5819
---------------------------
5821
:Capability: KVM_CAP_ARM_MTE
5822
:Architectures: arm64
5823
:Type: vm ioctl
5824
:Parameters: struct kvm_arm_copy_mte_tags
5825
:Returns: number of bytes copied, < 0 on error (-EINVAL for incorrect
5826
arguments, -EFAULT if memory cannot be accessed).
5828
::
5830
struct kvm_arm_copy_mte_tags {
5831
__u64 guest_ipa;
5832
__u64 length;
5833
void __user *addr;
5834
__u64 flags;
5835
__u64 reserved[2];
5836
};
5838
Copies Memory Tagging Extension (MTE) tags to/from guest tag memory. The
5839
``guest_ipa`` and ``length`` fields must be ``PAGE_SIZE`` aligned.
5840
``length`` must not be bigger than 2^31 - PAGE_SIZE bytes. The ``addr``
5841
field must point to a buffer which the tags will be copied to or from.
5843
``flags`` specifies the direction of copy, either ``KVM_ARM_TAGS_TO_GUEST`` or
5844
``KVM_ARM_TAGS_FROM_GUEST``.
5846
The size of the buffer to store the tags is ``(length / 16)`` bytes
5847
(granules in MTE are 16 bytes long). Each byte contains a single tag
5848
value. This matches the format of ``PTRACE_PEEKMTETAGS`` and
5849
``PTRACE_POKEMTETAGS``.
5851
If an error occurs before any data is copied then a negative error code is
5852
returned. If some tags have been copied before an error occurs then the number
5853
of bytes successfully copied is returned. If the call completes successfully
5854
then ``length`` is returned.
5856
4.131 KVM_GET_SREGS2
5857
--------------------
5859
:Capability: KVM_CAP_SREGS2
5860
:Architectures: x86
5861
:Type: vcpu ioctl
5862
:Parameters: struct kvm_sregs2 (out)
5863
:Returns: 0 on success, -1 on error
5865
Reads special registers from the vcpu.
5866
This ioctl (when supported) replaces the KVM_GET_SREGS.
5868
::
5870
struct kvm_sregs2 {
5871
/* out (KVM_GET_SREGS2) / in (KVM_SET_SREGS2) */
5872
struct kvm_segment cs, ds, es, fs, gs, ss;
5873
struct kvm_segment tr, ldt;
5874
struct kvm_dtable gdt, idt;
5875
__u64 cr0, cr2, cr3, cr4, cr8;
5876
__u64 efer;
5877
__u64 apic_base;
5878
__u64 flags;
5879
__u64 pdptrs[4];
5880
};
5882
flags values for ``kvm_sregs2``:
5884
``KVM_SREGS2_FLAGS_PDPTRS_VALID``
5886
Indicates that the struct contains valid PDPTR values.
5889
4.132 KVM_SET_SREGS2
5890
--------------------
5892
:Capability: KVM_CAP_SREGS2
5893
:Architectures: x86
5894
:Type: vcpu ioctl
5895
:Parameters: struct kvm_sregs2 (in)
5896
:Returns: 0 on success, -1 on error
5898
Writes special registers into the vcpu.
5899
See KVM_GET_SREGS2 for the data structures.
5900
This ioctl (when supported) replaces the KVM_SET_SREGS.
5902
4.133 KVM_GET_STATS_FD
5903
----------------------
5905
:Capability: KVM_CAP_STATS_BINARY_FD
5906
:Architectures: all
5907
:Type: vm ioctl, vcpu ioctl
5908
:Parameters: none
5909
:Returns: statistics file descriptor on success, < 0 on error
5911
Errors:
5913
====== ======================================================
5914
ENOMEM if the fd could not be created due to lack of memory
5915
EMFILE if the number of opened files exceeds the limit
5916
====== ======================================================
5918
The returned file descriptor can be used to read VM/vCPU statistics data in
5919
binary format. The data in the file descriptor consists of four blocks
5920
organized as follows:
5922
+-------------+
5923
| Header |
5924
+-------------+
5925
| id string |
5926
+-------------+
5927
| Descriptors |
5928
+-------------+
5929
| Stats Data |
5930
+-------------+
5932
Apart from the header starting at offset 0, please be aware that it is
5933
not guaranteed that the four blocks are adjacent or in the above order;
5934
the offsets of the id, descriptors and data blocks are found in the
5935
header. However, all four blocks are aligned to 64 bit offsets in the
5936
file and they do not overlap.
5938
All blocks except the data block are immutable. Userspace can read them
5939
only one time after retrieving the file descriptor, and then use ``pread`` or
5940
``lseek`` to read the statistics repeatedly.
5942
All data is in system endianness.
5944
The format of the header is as follows::
5946
struct kvm_stats_header {
5947
__u32 flags;
5948
__u32 name_size;
5949
__u32 num_desc;
5950
__u32 id_offset;
5951
__u32 desc_offset;
5952
__u32 data_offset;
5953
};
5955
The ``flags`` field is not used at the moment. It is always read as 0.
5957
The ``name_size`` field is the size (in byte) of the statistics name string
5958
(including trailing '\0') which is contained in the "id string" block and
5959
appended at the end of every descriptor.
5961
The ``num_desc`` field is the number of descriptors that are included in the
5962
descriptor block. (The actual number of values in the data block may be
5963
larger, since each descriptor may comprise more than one value).
5965
The ``id_offset`` field is the offset of the id string from the start of the
5966
file indicated by the file descriptor. It is a multiple of 8.
5968
The ``desc_offset`` field is the offset of the Descriptors block from the start
5969
of the file indicated by the file descriptor. It is a multiple of 8.
5971
The ``data_offset`` field is the offset of the Stats Data block from the start
5972
of the file indicated by the file descriptor. It is a multiple of 8.
5974
The id string block contains a string which identifies the file descriptor on
5975
which KVM_GET_STATS_FD was invoked. The size of the block, including the
5976
trailing ``'\0'``, is indicated by the ``name_size`` field in the header.
5978
The descriptors block is only needed to be read once for the lifetime of the
5979
file descriptor contains a sequence of ``struct kvm_stats_desc``, each followed
5980
by a string of size ``name_size``.
5981
::
5983
#define KVM_STATS_TYPE_SHIFT 0
5984
#define KVM_STATS_TYPE_MASK (0xF << KVM_STATS_TYPE_SHIFT)
5985
#define KVM_STATS_TYPE_CUMULATIVE (0x0 << KVM_STATS_TYPE_SHIFT)
5986
#define KVM_STATS_TYPE_INSTANT (0x1 << KVM_STATS_TYPE_SHIFT)
5987
#define KVM_STATS_TYPE_PEAK (0x2 << KVM_STATS_TYPE_SHIFT)
5988
#define KVM_STATS_TYPE_LINEAR_HIST (0x3 << KVM_STATS_TYPE_SHIFT)
5989
#define KVM_STATS_TYPE_LOG_HIST (0x4 << KVM_STATS_TYPE_SHIFT)
5990
#define KVM_STATS_TYPE_MAX KVM_STATS_TYPE_LOG_HIST
5992
#define KVM_STATS_UNIT_SHIFT 4
5993
#define KVM_STATS_UNIT_MASK (0xF << KVM_STATS_UNIT_SHIFT)
5994
#define KVM_STATS_UNIT_NONE (0x0 << KVM_STATS_UNIT_SHIFT)
5995
#define KVM_STATS_UNIT_BYTES (0x1 << KVM_STATS_UNIT_SHIFT)
5996
#define KVM_STATS_UNIT_SECONDS (0x2 << KVM_STATS_UNIT_SHIFT)
5997
#define KVM_STATS_UNIT_CYCLES (0x3 << KVM_STATS_UNIT_SHIFT)
5998
#define KVM_STATS_UNIT_BOOLEAN (0x4 << KVM_STATS_UNIT_SHIFT)
5999
#define KVM_STATS_UNIT_MAX KVM_STATS_UNIT_BOOLEAN
6001
#define KVM_STATS_BASE_SHIFT 8
6002
#define KVM_STATS_BASE_MASK (0xF << KVM_STATS_BASE_SHIFT)
6003
#define KVM_STATS_BASE_POW10 (0x0 << KVM_STATS_BASE_SHIFT)
6004
#define KVM_STATS_BASE_POW2 (0x1 << KVM_STATS_BASE_SHIFT)
6005
#define KVM_STATS_BASE_MAX KVM_STATS_BASE_POW2
6007
struct kvm_stats_desc {
6008
__u32 flags;
6009
__s16 exponent;
6010
__u16 size;
6011
__u32 offset;
6012
__u32 bucket_size;
6013
char name[];
6014
};
6016
The ``flags`` field contains the type and unit of the statistics data described
6017
by this descriptor. Its endianness is CPU native.
6018
The following flags are supported:
6020
Bits 0-3 of ``flags`` encode the type:
6022
* ``KVM_STATS_TYPE_CUMULATIVE``
6023
The statistics reports a cumulative count. The value of data can only be increased.
6024
Most of the counters used in KVM are of this type.
6025
The corresponding ``size`` field for this type is always 1.
6026
All cumulative statistics data are read/write.
6027
* ``KVM_STATS_TYPE_INSTANT``
6028
The statistics reports an instantaneous value. Its value can be increased or
6029
decreased. This type is usually used as a measurement of some resources,
6030
like the number of dirty pages, the number of large pages, etc.
6031
All instant statistics are read only.
6032
The corresponding ``size`` field for this type is always 1.
6033
* ``KVM_STATS_TYPE_PEAK``
6034
The statistics data reports a peak value, for example the maximum number
6035
of items in a hash table bucket, the longest time waited and so on.
6036
The value of data can only be increased.
6037
The corresponding ``size`` field for this type is always 1.
6038
* ``KVM_STATS_TYPE_LINEAR_HIST``
6039
The statistic is reported as a linear histogram. The number of
6040
buckets is specified by the ``size`` field. The size of buckets is specified
6041
by the ``hist_param`` field. The range of the Nth bucket (1 <= N < ``size``)
6042
is [``hist_param``*(N-1), ``hist_param``*N), while the range of the last
6043
bucket is [``hist_param``*(``size``-1), +INF). (+INF means positive infinity
6044
value.)
6045
* ``KVM_STATS_TYPE_LOG_HIST``
6046
The statistic is reported as a logarithmic histogram. The number of
6047
buckets is specified by the ``size`` field. The range of the first bucket is
6048
[0, 1), while the range of the last bucket is [pow(2, ``size``-2), +INF).
6049
Otherwise, The Nth bucket (1 < N < ``size``) covers
6050
[pow(2, N-2), pow(2, N-1)).
6052
Bits 4-7 of ``flags`` encode the unit:
6054
* ``KVM_STATS_UNIT_NONE``
6055
There is no unit for the value of statistics data. This usually means that
6056
the value is a simple counter of an event.
6057
* ``KVM_STATS_UNIT_BYTES``
6058
It indicates that the statistics data is used to measure memory size, in the
6059
unit of Byte, KiByte, MiByte, GiByte, etc. The unit of the data is
6060
determined by the ``exponent`` field in the descriptor.
6061
* ``KVM_STATS_UNIT_SECONDS``
6062
It indicates that the statistics data is used to measure time or latency.
6063
* ``KVM_STATS_UNIT_CYCLES``
6064
It indicates that the statistics data is used to measure CPU clock cycles.
6065
* ``KVM_STATS_UNIT_BOOLEAN``
6066
It indicates that the statistic will always be either 0 or 1. Boolean
6067
statistics of "peak" type will never go back from 1 to 0. Boolean
6068
statistics can be linear histograms (with two buckets) but not logarithmic
6069
histograms.
6071
Note that, in the case of histograms, the unit applies to the bucket
6072
ranges, while the bucket value indicates how many samples fell in the
6073
bucket's range.
6075
Bits 8-11 of ``flags``, together with ``exponent``, encode the scale of the
6076
unit:
6078
* ``KVM_STATS_BASE_POW10``
6079
The scale is based on power of 10. It is used for measurement of time and
6080
CPU clock cycles. For example, an exponent of -9 can be used with
6081
``KVM_STATS_UNIT_SECONDS`` to express that the unit is nanoseconds.
6082
* ``KVM_STATS_BASE_POW2``
6083
The scale is based on power of 2. It is used for measurement of memory size.
6084
For example, an exponent of 20 can be used with ``KVM_STATS_UNIT_BYTES`` to
6085
express that the unit is MiB.
6087
The ``size`` field is the number of values of this statistics data. Its
6088
value is usually 1 for most of simple statistics. 1 means it contains an
6089
unsigned 64bit data.
6091
The ``offset`` field is the offset from the start of Data Block to the start of
6092
the corresponding statistics data.
6094
The ``bucket_size`` field is used as a parameter for histogram statistics data.
6095
It is only used by linear histogram statistics data, specifying the size of a
6096
bucket in the unit expressed by bits 4-11 of ``flags`` together with ``exponent``.
6098
The ``name`` field is the name string of the statistics data. The name string
6099
starts at the end of ``struct kvm_stats_desc``. The maximum length including
6100
the trailing ``'\0'``, is indicated by ``name_size`` in the header.
6102
The Stats Data block contains an array of 64-bit values in the same order
6103
as the descriptors in Descriptors block.
6105
4.134 KVM_GET_XSAVE2
6106
--------------------
6108
:Capability: KVM_CAP_XSAVE2
6109
:Architectures: x86
6110
:Type: vcpu ioctl
6111
:Parameters: struct kvm_xsave (out)
6112
:Returns: 0 on success, -1 on error
6115
::
6117
struct kvm_xsave {
6118
__u32 region[1024];
6119
__u32 extra[0];
6120
};
6122
This ioctl would copy current vcpu's xsave struct to the userspace. It
6123
copies as many bytes as are returned by KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2)
6124
when invoked on the vm file descriptor. The size value returned by
6125
KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2) will always be at least 4096.
6126
Currently, it is only greater than 4096 if a dynamic feature has been
6127
enabled with ``arch_prctl()``, but this may change in the future.
6129
The offsets of the state save areas in struct kvm_xsave follow the contents
6130
of CPUID leaf 0xD on the host.
6132
4.135 KVM_XEN_HVM_EVTCHN_SEND
6133
-----------------------------
6135
:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_EVTCHN_SEND
6136
:Architectures: x86
6137
:Type: vm ioctl
6138
:Parameters: struct kvm_irq_routing_xen_evtchn
6139
:Returns: 0 on success, < 0 on error
6142
::
6144
struct kvm_irq_routing_xen_evtchn {
6145
__u32 port;
6146
__u32 vcpu;
6147
__u32 priority;
6148
};
6150
This ioctl injects an event channel interrupt directly to the guest vCPU.
6152
4.136 KVM_S390_PV_CPU_COMMAND
6153
-----------------------------
6155
:Capability: KVM_CAP_S390_PROTECTED_DUMP
6156
:Architectures: s390
6157
:Type: vcpu ioctl
6158
:Parameters: none
6159
:Returns: 0 on success, < 0 on error
6161
This ioctl closely mirrors `KVM_S390_PV_COMMAND` but handles requests
6162
for vcpus. It re-uses the kvm_s390_pv_dmp struct and hence also shares
6163
the command ids.
6165
**command:**
6167
KVM_PV_DUMP
6168
Presents an API that provides calls which facilitate dumping a vcpu
6169
of a protected VM.
6171
**subcommand:**
6173
KVM_PV_DUMP_CPU
6174
Provides encrypted dump data like register values.
6175
The length of the returned data is provided by uv_info.guest_cpu_stor_len.
6177
4.137 KVM_S390_ZPCI_OP
6178
----------------------
6180
:Capability: KVM_CAP_S390_ZPCI_OP
6181
:Architectures: s390
6182
:Type: vm ioctl
6183
:Parameters: struct kvm_s390_zpci_op (in)
6184
:Returns: 0 on success, <0 on error
6186
Used to manage hardware-assisted virtualization features for zPCI devices.
6188
Parameters are specified via the following structure::
6190
struct kvm_s390_zpci_op {
6191
/* in */
6192
__u32 fh; /* target device */
6193
__u8 op; /* operation to perform */
6194
__u8 pad[3];
6195
union {
6196
/* for KVM_S390_ZPCIOP_REG_AEN */
6197
struct {
6198
__u64 ibv; /* Guest addr of interrupt bit vector */
6199
__u64 sb; /* Guest addr of summary bit */
6200
__u32 flags;
6201
__u32 noi; /* Number of interrupts */
6202
__u8 isc; /* Guest interrupt subclass */
6203
__u8 sbo; /* Offset of guest summary bit vector */
6204
__u16 pad;
6205
} reg_aen;
6206
__u64 reserved[8];
6207
} u;
6208
};
6210
The type of operation is specified in the "op" field.
6211
KVM_S390_ZPCIOP_REG_AEN is used to register the VM for adapter event
6212
notification interpretation, which will allow firmware delivery of adapter
6213
events directly to the vm, with KVM providing a backup delivery mechanism;
6214
KVM_S390_ZPCIOP_DEREG_AEN is used to subsequently disable interpretation of
6215
adapter event notifications.
6217
The target zPCI function must also be specified via the "fh" field. For the
6218
KVM_S390_ZPCIOP_REG_AEN operation, additional information to establish firmware
6219
delivery must be provided via the "reg_aen" struct.
6221
The "pad" and "reserved" fields may be used for future extensions and should be
6222
set to 0s by userspace.
6224
4.138 KVM_ARM_SET_COUNTER_OFFSET
6225
--------------------------------
6227
:Capability: KVM_CAP_COUNTER_OFFSET
6228
:Architectures: arm64
6229
:Type: vm ioctl
6230
:Parameters: struct kvm_arm_counter_offset (in)
6231
:Returns: 0 on success, < 0 on error
6233
This capability indicates that userspace is able to apply a single VM-wide
6234
offset to both the virtual and physical counters as viewed by the guest
6235
using the KVM_ARM_SET_CNT_OFFSET ioctl and the following data structure:
6237
::
6239
struct kvm_arm_counter_offset {
6240
__u64 counter_offset;
6241
__u64 reserved;
6242
};
6244
The offset describes a number of counter cycles that are subtracted from
6245
both virtual and physical counter views (similar to the effects of the
6246
CNTVOFF_EL2 and CNTPOFF_EL2 system registers, but only global). The offset
6247
always applies to all vcpus (already created or created after this ioctl)
6248
for this VM.
6250
It is userspace's responsibility to compute the offset based, for example,
6251
on previous values of the guest counters.
6253
Any value other than 0 for the "reserved" field may result in an error
6254
(-EINVAL) being returned. This ioctl can also return -EBUSY if any vcpu
6255
ioctl is issued concurrently.
6257
Note that using this ioctl results in KVM ignoring subsequent userspace
6258
writes to the CNTVCT_EL0 and CNTPCT_EL0 registers using the SET_ONE_REG
6259
interface. No error will be returned, but the resulting offset will not be
6260
applied.
6262
.. _KVM_ARM_GET_REG_WRITABLE_MASKS:
6264
4.139 KVM_ARM_GET_REG_WRITABLE_MASKS
6265
------------------------------------
6267
:Capability: KVM_CAP_ARM_SUPPORTED_REG_MASK_RANGES
6268
:Architectures: arm64
6269
:Type: vm ioctl
6270
:Parameters: struct reg_mask_range (in/out)
6271
:Returns: 0 on success, < 0 on error
6274
::
6276
#define KVM_ARM_FEATURE_ID_RANGE 0
6277
#define KVM_ARM_FEATURE_ID_RANGE_SIZE (3 * 8 * 8)
6279
struct reg_mask_range {
6280
__u64 addr; /* Pointer to mask array */
6281
__u32 range; /* Requested range */
6282
__u32 reserved[13];
6283
};
6285
This ioctl copies the writable masks for a selected range of registers to
6286
userspace.
6288
The ``addr`` field is a pointer to the destination array where KVM copies
6289
the writable masks.
6291
The ``range`` field indicates the requested range of registers.
6292
``KVM_CHECK_EXTENSION`` for the ``KVM_CAP_ARM_SUPPORTED_REG_MASK_RANGES``
6293
capability returns the supported ranges, expressed as a set of flags. Each
6294
flag's bit index represents a possible value for the ``range`` field.
6295
All other values are reserved for future use and KVM may return an error.
6297
The ``reserved[13]`` array is reserved for future use and should be 0, or
6298
KVM may return an error.
6300
KVM_ARM_FEATURE_ID_RANGE (0)
6301
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6303
The Feature ID range is defined as the AArch64 System register space with
6304
op0==3, op1=={0, 1, 3}, CRn==0, CRm=={0-7}, op2=={0-7}.
6306
The mask returned array pointed to by ``addr`` is indexed by the macro
6307
``ARM64_FEATURE_ID_RANGE_IDX(op0, op1, crn, crm, op2)``, allowing userspace
6308
to know what fields can be changed for the system register described by
6309
``op0, op1, crn, crm, op2``. KVM rejects ID register values that describe a
6310
superset of the features supported by the system.
6312
4.140 KVM_SET_USER_MEMORY_REGION2
6313
---------------------------------
6315
:Capability: KVM_CAP_USER_MEMORY2
6316
:Architectures: all
6317
:Type: vm ioctl
6318
:Parameters: struct kvm_userspace_memory_region2 (in)
6319
:Returns: 0 on success, -1 on error
6321
KVM_SET_USER_MEMORY_REGION2 is an extension to KVM_SET_USER_MEMORY_REGION that
6322
allows mapping guest_memfd memory into a guest. All fields shared with
6323
KVM_SET_USER_MEMORY_REGION identically. Userspace can set KVM_MEM_GUEST_MEMFD
6324
in flags to have KVM bind the memory region to a given guest_memfd range of
6325
[guest_memfd_offset, guest_memfd_offset + memory_size]. The target guest_memfd
6326
must point at a file created via KVM_CREATE_GUEST_MEMFD on the current VM, and
6327
the target range must not be bound to any other memory region. All standard
6328
bounds checks apply (use common sense).
6330
::
6332
struct kvm_userspace_memory_region2 {
6333
__u32 slot;
6334
__u32 flags;
6335
__u64 guest_phys_addr;
6336
__u64 memory_size; /* bytes */
6337
__u64 userspace_addr; /* start of the userspace allocated memory */
6338
__u64 guest_memfd_offset;
6339
__u32 guest_memfd;
6340
__u32 pad1;
6341
__u64 pad2[14];
6342
};
6344
A KVM_MEM_GUEST_MEMFD region _must_ have a valid guest_memfd (private memory) and
6345
userspace_addr (shared memory). However, "valid" for userspace_addr simply
6346
means that the address itself must be a legal userspace address. The backing
6347
mapping for userspace_addr is not required to be valid/populated at the time of
6348
KVM_SET_USER_MEMORY_REGION2, e.g. shared memory can be lazily mapped/allocated
6349
on-demand.
6351
When mapping a gfn into the guest, KVM selects shared vs. private, i.e consumes
6352
userspace_addr vs. guest_memfd, based on the gfn's KVM_MEMORY_ATTRIBUTE_PRIVATE
6353
state. At VM creation time, all memory is shared, i.e. the PRIVATE attribute
6354
is '0' for all gfns. Userspace can control whether memory is shared/private by
6355
toggling KVM_MEMORY_ATTRIBUTE_PRIVATE via KVM_SET_MEMORY_ATTRIBUTES as needed.
6357
S390:
6358
^^^^^
6360
Returns -EINVAL if the VM has the KVM_VM_S390_UCONTROL flag set.
6361
Returns -EINVAL if called on a protected VM.
6363
4.141 KVM_SET_MEMORY_ATTRIBUTES
6364
-------------------------------
6366
:Capability: KVM_CAP_MEMORY_ATTRIBUTES
6367
:Architectures: x86
6368
:Type: vm ioctl
6369
:Parameters: struct kvm_memory_attributes (in)
6370
:Returns: 0 on success, <0 on error
6372
KVM_SET_MEMORY_ATTRIBUTES allows userspace to set memory attributes for a range
6373
of guest physical memory.
6375
::
6377
struct kvm_memory_attributes {
6378
__u64 address;
6379
__u64 size;
6380
__u64 attributes;
6381
__u64 flags;
6382
};
6384
#define KVM_MEMORY_ATTRIBUTE_PRIVATE (1ULL << 3)
6386
The address and size must be page aligned. The supported attributes can be
6387
retrieved via ioctl(KVM_CHECK_EXTENSION) on KVM_CAP_MEMORY_ATTRIBUTES. If
6388
executed on a VM, KVM_CAP_MEMORY_ATTRIBUTES precisely returns the attributes
6389
supported by that VM. If executed at system scope, KVM_CAP_MEMORY_ATTRIBUTES
6390
returns all attributes supported by KVM. The only attribute defined at this
6391
time is KVM_MEMORY_ATTRIBUTE_PRIVATE, which marks the associated gfn as being
6392
guest private memory.
6394
Note, there is no "get" API. Userspace is responsible for explicitly tracking
6395
the state of a gfn/page as needed.
6397
The "flags" field is reserved for future extensions and must be '0'.
6399
4.142 KVM_CREATE_GUEST_MEMFD
6400
----------------------------
6402
:Capability: KVM_CAP_GUEST_MEMFD
6403
:Architectures: none
6404
:Type: vm ioctl
6405
:Parameters: struct kvm_create_guest_memfd(in)
6406
:Returns: A file descriptor on success, <0 on error
6408
KVM_CREATE_GUEST_MEMFD creates an anonymous file and returns a file descriptor
6409
that refers to it. guest_memfd files are roughly analogous to files created
6410
via memfd_create(), e.g. guest_memfd files live in RAM, have volatile storage,
6411
and are automatically released when the last reference is dropped. Unlike
6412
"regular" memfd_create() files, guest_memfd files are bound to their owning
6413
virtual machine (see below), cannot be mapped, read, or written by userspace,
6414
and cannot be resized (guest_memfd files do however support PUNCH_HOLE).
6416
::
6418
struct kvm_create_guest_memfd {
6419
__u64 size;
6420
__u64 flags;
6421
__u64 reserved[6];
6422
};
6424
Conceptually, the inode backing a guest_memfd file represents physical memory,
6425
i.e. is coupled to the virtual machine as a thing, not to a "struct kvm". The
6426
file itself, which is bound to a "struct kvm", is that instance's view of the
6427
underlying memory, e.g. effectively provides the translation of guest addresses
6428
to host memory. This allows for use cases where multiple KVM structures are
6429
used to manage a single virtual machine, e.g. when performing intrahost
6430
migration of a virtual machine.
6432
KVM currently only supports mapping guest_memfd via KVM_SET_USER_MEMORY_REGION2,
6433
and more specifically via the guest_memfd and guest_memfd_offset fields in
6434
"struct kvm_userspace_memory_region2", where guest_memfd_offset is the offset
6435
into the guest_memfd instance. For a given guest_memfd file, there can be at
6436
most one mapping per page, i.e. binding multiple memory regions to a single
6437
guest_memfd range is not allowed (any number of memory regions can be bound to
6438
a single guest_memfd file, but the bound ranges must not overlap).
6440
The capability KVM_CAP_GUEST_MEMFD_FLAGS enumerates the `flags` that can be
6441
specified via KVM_CREATE_GUEST_MEMFD. Currently defined flags:
6443
============================ ================================================
6444
GUEST_MEMFD_FLAG_MMAP Enable using mmap() on the guest_memfd file
6445
descriptor.
6446
GUEST_MEMFD_FLAG_INIT_SHARED Make all memory in the file shared during
6447
KVM_CREATE_GUEST_MEMFD (memory files created
6448
without INIT_SHARED will be marked private).
6449
Shared memory can be faulted into host userspace
6450
page tables. Private memory cannot.
6451
============================ ================================================
6453
When the KVM MMU performs a PFN lookup to service a guest fault and the backing
6454
guest_memfd has the GUEST_MEMFD_FLAG_MMAP set, then the fault will always be
6455
consumed from guest_memfd, regardless of whether it is a shared or a private
6456
fault.
6458
See KVM_SET_USER_MEMORY_REGION2 for additional details.
6460
4.143 KVM_PRE_FAULT_MEMORY
6461
---------------------------
6463
:Capability: KVM_CAP_PRE_FAULT_MEMORY
6464
:Architectures: none
6465
:Type: vcpu ioctl
6466
:Parameters: struct kvm_pre_fault_memory (in/out)
6467
:Returns: 0 if at least one page is processed, < 0 on error
6469
Errors:
6471
========== ===============================================================
6472
EINVAL The specified `gpa` and `size` were invalid (e.g. not
6473
page aligned, causes an overflow, or size is zero).
6474
ENOENT The specified `gpa` is outside defined memslots.
6475
EINTR An unmasked signal is pending and no page was processed.
6476
EFAULT The parameter address was invalid.
6477
EOPNOTSUPP Mapping memory for a GPA is unsupported by the
6478
hypervisor, and/or for the current vCPU state/mode.
6479
EIO unexpected error conditions (also causes a WARN)
6480
========== ===============================================================
6482
::
6484
struct kvm_pre_fault_memory {
6485
/* in/out */
6486
__u64 gpa;
6487
__u64 size;
6488
/* in */
6489
__u64 flags;
6490
__u64 padding[5];
6491
};
6493
KVM_PRE_FAULT_MEMORY populates KVM's stage-2 page tables used to map memory
6494
for the current vCPU state. KVM maps memory as if the vCPU generated a
6495
stage-2 read page fault, e.g. faults in memory as needed, but doesn't break
6496
CoW. However, KVM does not mark any newly created stage-2 PTE as Accessed.
6498
In the case of confidential VM types where there is an initial set up of
6499
private guest memory before the guest is 'finalized'/measured, this ioctl
6500
should only be issued after completing all the necessary setup to put the
6501
guest into a 'finalized' state so that the above semantics can be reliably
6502
ensured.
6504
In some cases, multiple vCPUs might share the page tables. In this
6505
case, the ioctl can be called in parallel.
6507
When the ioctl returns, the input values are updated to point to the
6508
remaining range. If `size` > 0 on return, the caller can just issue
6509
the ioctl again with the same `struct kvm_map_memory` argument.
6511
Shadow page tables cannot support this ioctl because they
6512
are indexed by virtual address or nested guest physical address.
6513
Calling this ioctl when the guest is using shadow page tables (for
6514
example because it is running a nested guest with nested page tables)
6515
will fail with `EOPNOTSUPP` even if `KVM_CHECK_EXTENSION` reports
6516
the capability to be present.
6518
`flags` must currently be zero.
6521
.. _kvm_run:
6523
5. The kvm_run structure
6524
========================
6526
Application code obtains a pointer to the kvm_run structure by
6527
mmap()ing a vcpu fd. From that point, application code can control
6528
execution by changing fields in kvm_run prior to calling the KVM_RUN
6529
ioctl, and obtain information about the reason KVM_RUN returned by
6530
looking up structure members.
6532
::
6534
struct kvm_run {
6535
/* in */
6536
__u8 request_interrupt_window;
6538
Request that KVM_RUN return when it becomes possible to inject external
6539
interrupts into the guest. Useful in conjunction with KVM_INTERRUPT.
6541
::
6543
__u8 immediate_exit;
6545
This field is polled once when KVM_RUN starts; if non-zero, KVM_RUN
6546
exits immediately, returning -EINTR. In the common scenario where a
6547
signal is used to "kick" a VCPU out of KVM_RUN, this field can be used
6548
to avoid usage of KVM_SET_SIGNAL_MASK, which has worse scalability.
6549
Rather than blocking the signal outside KVM_RUN, userspace can set up
6550
a signal handler that sets run->immediate_exit to a non-zero value.
6552
This field is ignored if KVM_CAP_IMMEDIATE_EXIT is not available.
6554
::
6556
__u8 padding1[6];
6558
/* out */
6559
__u32 exit_reason;
6561
When KVM_RUN has returned successfully (return value 0), this informs
6562
application code why KVM_RUN has returned. Allowable values for this
6563
field are detailed below.
6565
::
6567
__u8 ready_for_interrupt_injection;
6569
If request_interrupt_window has been specified, this field indicates
6570
an interrupt can be injected now with KVM_INTERRUPT.
6572
::
6574
__u8 if_flag;
6576
The value of the current interrupt flag. Only valid if in-kernel
6577
local APIC is not used.
6579
::
6581
__u16 flags;
6583
More architecture-specific flags detailing state of the VCPU that may
6584
affect the device's behavior. Current defined flags::
6586
/* x86, set if the VCPU is in system management mode */
6587
#define KVM_RUN_X86_SMM (1 << 0)
6588
/* x86, set if bus lock detected in VM */
6589
#define KVM_RUN_X86_BUS_LOCK (1 << 1)
6590
/* x86, set if the VCPU is executing a nested (L2) guest */
6591
#define KVM_RUN_X86_GUEST_MODE (1 << 2)
6593
/* arm64, set for KVM_EXIT_DEBUG */
6594
#define KVM_DEBUG_ARCH_HSR_HIGH_VALID (1 << 0)
6596
::
6598
/* in (pre_kvm_run), out (post_kvm_run) */
6599
__u64 cr8;
6601
The value of the cr8 register. Only valid if in-kernel local APIC is
6602
not used. Both input and output.
6604
::
6606
__u64 apic_base;
6608
The value of the APIC BASE msr. Only valid if in-kernel local
6609
APIC is not used. Both input and output.
6611
::
6613
union {
6614
/* KVM_EXIT_UNKNOWN */
6615
struct {
6616
__u64 hardware_exit_reason;
6617
} hw;
6619
If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown
6620
reasons. Further architecture-specific information is available in
6621
hardware_exit_reason.
6623
::
6625
/* KVM_EXIT_FAIL_ENTRY */
6626
struct {
6627
__u64 hardware_entry_failure_reason;
6628
__u32 cpu; /* if KVM_LAST_CPU */
6629
} fail_entry;
6631
If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due
6632
to unknown reasons. Further architecture-specific information is
6633
available in hardware_entry_failure_reason.
6635
::
6637
/* KVM_EXIT_EXCEPTION */
6638
struct {
6639
__u32 exception;
6640
__u32 error_code;
6641
} ex;
6643
Unused.
6645
::
6647
/* KVM_EXIT_IO */
6648
struct {
6649
#define KVM_EXIT_IO_IN 0
6650
#define KVM_EXIT_IO_OUT 1
6651
__u8 direction;
6652
__u8 size; /* bytes */
6653
__u16 port;
6654
__u32 count;
6655
__u64 data_offset; /* relative to kvm_run start */
6656
} io;
6658
If exit_reason is KVM_EXIT_IO, then the vcpu has
6659
executed a port I/O instruction which could not be satisfied by kvm.
6660
data_offset describes where the data is located (KVM_EXIT_IO_OUT) or
6661
where kvm expects application code to place the data for the next
6662
KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a packed array.
6664
::
6666
/* KVM_EXIT_DEBUG */
6667
struct {
6668
struct kvm_debug_exit_arch arch;
6669
} debug;
6671
If the exit_reason is KVM_EXIT_DEBUG, then a vcpu is processing a debug event
6672
for which architecture specific information is returned.
6674
::
6676
/* KVM_EXIT_MMIO */
6677
struct {
6678
__u64 phys_addr;
6679
__u8 data[8];
6680
__u32 len;
6681
__u8 is_write;
6682
} mmio;
6684
If exit_reason is KVM_EXIT_MMIO, then the vcpu has
6685
executed a memory-mapped I/O instruction which could not be satisfied
6686
by kvm. The 'data' member contains the written data if 'is_write' is
6687
true, and should be filled by application code otherwise.
6689
The 'data' member contains, in its first 'len' bytes, the value as it would
6690
appear if the VCPU performed a load or store of the appropriate width directly
6691
to the byte array.
6693
.. note::
6695
For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR, KVM_EXIT_XEN,
6696
KVM_EXIT_EPR, KVM_EXIT_HYPERCALL, KVM_EXIT_TDX,
6697
KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR the corresponding
6698
operations are complete (and guest state is consistent) only after userspace
6699
has re-entered the kernel with KVM_RUN. The kernel side will first finish
6700
incomplete operations and then check for pending signals.
6702
The pending state of the operation is not preserved in state which is
6703
visible to userspace, thus userspace should ensure that the operation is
6704
completed before performing a live migration. Userspace can re-enter the
6705
guest with an unmasked signal pending or with the immediate_exit field set
6706
to complete pending operations without allowing any further instructions
6707
to be executed.
6709
::
6711
/* KVM_EXIT_HYPERCALL */
6712
struct {
6713
__u64 nr;
6714
__u64 args[6];
6715
__u64 ret;
6716
__u64 flags;
6717
} hypercall;
6720
It is strongly recommended that userspace use ``KVM_EXIT_IO`` (x86) or
6721
``KVM_EXIT_MMIO`` (all except s390) to implement functionality that
6722
requires a guest to interact with host userspace.
6724
.. note:: KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
6726
For arm64:
6727
----------
6729
SMCCC exits can be enabled depending on the configuration of the SMCCC
6730
filter. See the Documentation/virt/kvm/devices/vm.rst
6731
``KVM_ARM_SMCCC_FILTER`` for more details.
6733
``nr`` contains the function ID of the guest's SMCCC call. Userspace is
6734
expected to use the ``KVM_GET_ONE_REG`` ioctl to retrieve the call
6735
parameters from the vCPU's GPRs.
6737
Definition of ``flags``:
6738
- ``KVM_HYPERCALL_EXIT_SMC``: Indicates that the guest used the SMC
6739
conduit to initiate the SMCCC call. If this bit is 0 then the guest
6740
used the HVC conduit for the SMCCC call.
6742
- ``KVM_HYPERCALL_EXIT_16BIT``: Indicates that the guest used a 16bit
6743
instruction to initiate the SMCCC call. If this bit is 0 then the
6744
guest used a 32bit instruction. An AArch64 guest always has this
6745
bit set to 0.
6747
At the point of exit, PC points to the instruction immediately following
6748
the trapping instruction.
6750
::
6752
/* KVM_EXIT_TPR_ACCESS */
6753
struct {
6754
__u64 rip;
6755
__u32 is_write;
6756
__u32 pad;
6757
} tpr_access;
6759
To be documented (KVM_TPR_ACCESS_REPORTING).
6761
::
6763
/* KVM_EXIT_S390_SIEIC */
6764
struct {
6765
__u8 icptcode;
6766
__u64 mask; /* psw upper half */
6767
__u64 addr; /* psw lower half */
6768
__u16 ipa;
6769
__u32 ipb;
6770
} s390_sieic;
6772
s390 specific.
6774
::
6776
/* KVM_EXIT_S390_RESET */
6777
#define KVM_S390_RESET_POR 1
6778
#define KVM_S390_RESET_CLEAR 2
6779
#define KVM_S390_RESET_SUBSYSTEM 4
6780
#define KVM_S390_RESET_CPU_INIT 8
6781
#define KVM_S390_RESET_IPL 16
6782
__u64 s390_reset_flags;
6784
s390 specific.
6786
::
6788
/* KVM_EXIT_S390_UCONTROL */
6789
struct {
6790
__u64 trans_exc_code;
6791
__u32 pgm_code;
6792
} s390_ucontrol;
6794
s390 specific. A page fault has occurred for a user controlled virtual
6795
machine (KVM_VM_S390_UNCONTROL) on its host page table that cannot be
6796
resolved by the kernel.
6797
The program code and the translation exception code that were placed
6798
in the cpu's lowcore are presented here as defined by the z Architecture
6799
Principles of Operation Book in the Chapter for Dynamic Address Translation
6800
(DAT)
6802
::
6804
/* KVM_EXIT_DCR */
6805
struct {
6806
__u32 dcrn;
6807
__u32 data;
6808
__u8 is_write;
6809
} dcr;
6811
Deprecated - was used for 440 KVM.
6813
::
6815
/* KVM_EXIT_OSI */
6816
struct {
6817
__u64 gprs[32];
6818
} osi;
6820
MOL uses a special hypercall interface it calls 'OSI'. To enable it, we catch
6821
hypercalls and exit with this exit struct that contains all the guest gprs.
6823
If exit_reason is KVM_EXIT_OSI, then the vcpu has triggered such a hypercall.
6824
Userspace can now handle the hypercall and when it's done modify the gprs as
6825
necessary. Upon guest entry all guest GPRs will then be replaced by the values
6826
in this struct.
6828
::
6830
/* KVM_EXIT_PAPR_HCALL */
6831
struct {
6832
__u64 nr;
6833
__u64 ret;
6834
__u64 args[9];
6835
} papr_hcall;
6837
This is used on 64-bit PowerPC when emulating a pSeries partition,
6838
e.g. with the 'pseries' machine type in qemu. It occurs when the
6839
guest does a hypercall using the 'sc 1' instruction. The 'nr' field
6840
contains the hypercall number (from the guest R3), and 'args' contains
6841
the arguments (from the guest R4 - R12). Userspace should put the
6842
return code in 'ret' and any extra returned values in args[].
6843
The possible hypercalls are defined in the Power Architecture Platform
6844
Requirements (PAPR) document available from www.power.org (free
6845
developer registration required to access it).
6847
::
6849
/* KVM_EXIT_S390_TSCH */
6850
struct {
6851
__u16 subchannel_id;
6852
__u16 subchannel_nr;
6853
__u32 io_int_parm;
6854
__u32 io_int_word;
6855
__u32 ipb;
6856
__u8 dequeued;
6857
} s390_tsch;
6859
s390 specific. This exit occurs when KVM_CAP_S390_CSS_SUPPORT has been enabled
6860
and TEST SUBCHANNEL was intercepted. If dequeued is set, a pending I/O
6861
interrupt for the target subchannel has been dequeued and subchannel_id,
6862
subchannel_nr, io_int_parm and io_int_word contain the parameters for that
6863
interrupt. ipb is needed for instruction parameter decoding.
6865
::
6867
/* KVM_EXIT_EPR */
6868
struct {
6869
__u32 epr;
6870
} epr;
6872
On FSL BookE PowerPC chips, the interrupt controller has a fast patch
6873
interrupt acknowledge path to the core. When the core successfully
6874
delivers an interrupt, it automatically populates the EPR register with
6875
the interrupt vector number and acknowledges the interrupt inside
6876
the interrupt controller.
6878
In case the interrupt controller lives in user space, we need to do
6879
the interrupt acknowledge cycle through it to fetch the next to be
6880
delivered interrupt vector using this exit.
6882
It gets triggered whenever both KVM_CAP_PPC_EPR are enabled and an
6883
external interrupt has just been delivered into the guest. User space
6884
should put the acknowledged interrupt vector into the 'epr' field.
6886
::
6888
/* KVM_EXIT_SYSTEM_EVENT */
6889
struct {
6890
#define KVM_SYSTEM_EVENT_SHUTDOWN 1
6891
#define KVM_SYSTEM_EVENT_RESET 2
6892
#define KVM_SYSTEM_EVENT_CRASH 3
6893
#define KVM_SYSTEM_EVENT_WAKEUP 4
6894
#define KVM_SYSTEM_EVENT_SUSPEND 5
6895
#define KVM_SYSTEM_EVENT_SEV_TERM 6
6896
#define KVM_SYSTEM_EVENT_TDX_FATAL 7
6897
__u32 type;
6898
__u32 ndata;
6899
__u64 data[16];
6900
} system_event;
6902
If exit_reason is KVM_EXIT_SYSTEM_EVENT then the vcpu has triggered
6903
a system-level event using some architecture specific mechanism (hypercall
6904
or some special instruction). In case of ARM64, this is triggered using
6905
HVC instruction based PSCI call from the vcpu.
6907
The 'type' field describes the system-level event type.
6908
Valid values for 'type' are:
6910
- KVM_SYSTEM_EVENT_SHUTDOWN -- the guest has requested a shutdown of the
6911
VM. Userspace is not obliged to honour this, and if it does honour
6912
this does not need to destroy the VM synchronously (ie it may call
6913
KVM_RUN again before shutdown finally occurs).
6914
- KVM_SYSTEM_EVENT_RESET -- the guest has requested a reset of the VM.
6915
As with SHUTDOWN, userspace can choose to ignore the request, or
6916
to schedule the reset to occur in the future and may call KVM_RUN again.
6917
- KVM_SYSTEM_EVENT_CRASH -- the guest crash occurred and the guest
6918
has requested a crash condition maintenance. Userspace can choose
6919
to ignore the request, or to gather VM memory core dump and/or
6920
reset/shutdown of the VM.
6921
- KVM_SYSTEM_EVENT_SEV_TERM -- an AMD SEV guest requested termination.
6922
The guest physical address of the guest's GHCB is stored in `data[0]`.
6923
- KVM_SYSTEM_EVENT_TDX_FATAL -- a TDX guest reported a fatal error state.
6924
KVM doesn't do any parsing or conversion, it just dumps 16 general-purpose
6925
registers to userspace, in ascending order of the 4-bit indices for x86-64
6926
general-purpose registers in instruction encoding, as defined in the Intel
6927
SDM.
6928
- KVM_SYSTEM_EVENT_WAKEUP -- the exiting vCPU is in a suspended state and
6929
KVM has recognized a wakeup event. Userspace may honor this event by
6930
marking the exiting vCPU as runnable, or deny it and call KVM_RUN again.
6931
- KVM_SYSTEM_EVENT_SUSPEND -- the guest has requested a suspension of
6932
the VM.
6934
If KVM_CAP_SYSTEM_EVENT_DATA is present, the 'data' field can contain
6935
architecture specific information for the system-level event. Only
6936
the first `ndata` items (possibly zero) of the data array are valid.
6938
- for arm64, data[0] is set to KVM_SYSTEM_EVENT_RESET_FLAG_PSCI_RESET2 if
6939
the guest issued a SYSTEM_RESET2 call according to v1.1 of the PSCI
6940
specification.
6942
- for arm64, data[0] is set to KVM_SYSTEM_EVENT_SHUTDOWN_FLAG_PSCI_OFF2
6943
if the guest issued a SYSTEM_OFF2 call according to v1.3 of the PSCI
6944
specification.
6946
- for RISC-V, data[0] is set to the value of the second argument of the
6947
``sbi_system_reset`` call.
6949
Previous versions of Linux defined a `flags` member in this struct. The
6950
field is now aliased to `data[0]`. Userspace can assume that it is only
6951
written if ndata is greater than 0.
6953
For arm/arm64:
6954
--------------
6956
KVM_SYSTEM_EVENT_SUSPEND exits are enabled with the
6957
KVM_CAP_ARM_SYSTEM_SUSPEND VM capability. If a guest invokes the PSCI
6958
SYSTEM_SUSPEND function, KVM will exit to userspace with this event
6959
type.
6961
It is the sole responsibility of userspace to implement the PSCI
6962
SYSTEM_SUSPEND call according to ARM DEN0022D.b 5.19 "SYSTEM_SUSPEND".
6963
KVM does not change the vCPU's state before exiting to userspace, so
6964
the call parameters are left in-place in the vCPU registers.
6966
Userspace is _required_ to take action for such an exit. It must
6967
either:
6969
- Honor the guest request to suspend the VM. Userspace can request
6970
in-kernel emulation of suspension by setting the calling vCPU's
6971
state to KVM_MP_STATE_SUSPENDED. Userspace must configure the vCPU's
6972
state according to the parameters passed to the PSCI function when
6973
the calling vCPU is resumed. See ARM DEN0022D.b 5.19.1 "Intended use"
6974
for details on the function parameters.
6976
- Deny the guest request to suspend the VM. See ARM DEN0022D.b 5.19.2
6977
"Caller responsibilities" for possible return values.
6979
Hibernation using the PSCI SYSTEM_OFF2 call is enabled when PSCI v1.3
6980
is enabled. If a guest invokes the PSCI SYSTEM_OFF2 function, KVM will
6981
exit to userspace with the KVM_SYSTEM_EVENT_SHUTDOWN event type and with
6982
data[0] set to KVM_SYSTEM_EVENT_SHUTDOWN_FLAG_PSCI_OFF2. The only
6983
supported hibernate type for the SYSTEM_OFF2 function is HIBERNATE_OFF.
6985
::
6987
/* KVM_EXIT_IOAPIC_EOI */
6988
struct {
6989
__u8 vector;
6990
} eoi;
6992
Indicates that the VCPU's in-kernel local APIC received an EOI for a
6993
level-triggered IOAPIC interrupt. This exit only triggers when the
6994
IOAPIC is implemented in userspace (i.e. KVM_CAP_SPLIT_IRQCHIP is enabled);
6995
the userspace IOAPIC should process the EOI and retrigger the interrupt if
6996
it is still asserted. Vector is the LAPIC interrupt vector for which the
6997
EOI was received.
6999
::
7001
struct kvm_hyperv_exit {
7002
#define KVM_EXIT_HYPERV_SYNIC 1
7003
#define KVM_EXIT_HYPERV_HCALL 2
7004
#define KVM_EXIT_HYPERV_SYNDBG 3
7005
__u32 type;
7006
__u32 pad1;
7007
union {
7008
struct {
7009
__u32 msr;
7010
__u32 pad2;
7011
__u64 control;
7012
__u64 evt_page;
7013
__u64 msg_page;
7014
} synic;
7015
struct {
7016
__u64 input;
7017
__u64 result;
7018
__u64 params[2];
7019
} hcall;
7020
struct {
7021
__u32 msr;
7022
__u32 pad2;
7023
__u64 control;
7024
__u64 status;
7025
__u64 send_page;
7026
__u64 recv_page;
7027
__u64 pending_page;
7028
} syndbg;
7029
} u;
7030
};
7031
/* KVM_EXIT_HYPERV */
7032
struct kvm_hyperv_exit hyperv;
7034
Indicates that the VCPU exits into userspace to process some tasks
7035
related to Hyper-V emulation.
7037
Valid values for 'type' are:
7039
- KVM_EXIT_HYPERV_SYNIC -- synchronously notify user-space about
7041
Hyper-V SynIC state change. Notification is used to remap SynIC
7042
event/message pages and to enable/disable SynIC messages/events processing
7043
in userspace.
7045
- KVM_EXIT_HYPERV_SYNDBG -- synchronously notify user-space about
7047
Hyper-V Synthetic debugger state change. Notification is used to either update
7048
the pending_page location or to send a control command (send the buffer located
7049
in send_page or recv a buffer to recv_page).
7051
::
7053
/* KVM_EXIT_ARM_NISV */
7054
struct {
7055
__u64 esr_iss;
7056
__u64 fault_ipa;
7057
} arm_nisv;
7059
Used on arm64 systems. If a guest accesses memory not in a memslot,
7060
KVM will typically return to userspace and ask it to do MMIO emulation on its
7061
behalf. However, for certain classes of instructions, no instruction decode
7062
(direction, length of memory access) is provided, and fetching and decoding
7063
the instruction from the VM is overly complicated to live in the kernel.
7065
Historically, when this situation occurred, KVM would print a warning and kill
7066
the VM. KVM assumed that if the guest accessed non-memslot memory, it was
7067
trying to do I/O, which just couldn't be emulated, and the warning message was
7068
phrased accordingly. However, what happened more often was that a guest bug
7069
caused access outside the guest memory areas which should lead to a more
7070
meaningful warning message and an external abort in the guest, if the access
7071
did not fall within an I/O window.
7073
Userspace implementations can query for KVM_CAP_ARM_NISV_TO_USER, and enable
7074
this capability at VM creation. Once this is done, these types of errors will
7075
instead return to userspace with KVM_EXIT_ARM_NISV, with the valid bits from
7076
the ESR_EL2 in the esr_iss field, and the faulting IPA in the fault_ipa field.
7077
Userspace can either fix up the access if it's actually an I/O access by
7078
decoding the instruction from guest memory (if it's very brave) and continue
7079
executing the guest, or it can decide to suspend, dump, or restart the guest.
7081
Note that KVM does not skip the faulting instruction as it does for
7082
KVM_EXIT_MMIO, but userspace has to emulate any change to the processing state
7083
if it decides to decode and emulate the instruction.
7085
This feature isn't available to protected VMs, as userspace does not
7086
have access to the state that is required to perform the emulation.
7087
Instead, a data abort exception is directly injected in the guest.
7088
Note that although KVM_CAP_ARM_NISV_TO_USER will be reported if
7089
queried outside of a protected VM context, the feature will not be
7090
exposed if queried on a protected VM file descriptor.
7092
::
7094
/* KVM_EXIT_X86_RDMSR / KVM_EXIT_X86_WRMSR */
7095
struct {
7096
__u8 error; /* user -> kernel */
7097
__u8 pad[7];
7098
__u32 reason; /* kernel -> user */
7099
__u32 index; /* kernel -> user */
7100
__u64 data; /* kernel <-> user */
7101
} msr;
7103
Used on x86 systems. When the VM capability KVM_CAP_X86_USER_SPACE_MSR is
7104
enabled, MSR accesses to registers that would invoke a #GP by KVM kernel code
7105
may instead trigger a KVM_EXIT_X86_RDMSR exit for reads and KVM_EXIT_X86_WRMSR
7106
exit for writes.
7108
The "reason" field specifies why the MSR interception occurred. Userspace will
7109
only receive MSR exits when a particular reason was requested during through
7110
ENABLE_CAP. Currently valid exit reasons are:
7112
============================ ========================================
7113
KVM_MSR_EXIT_REASON_UNKNOWN access to MSR that is unknown to KVM
7114
KVM_MSR_EXIT_REASON_INVAL access to invalid MSRs or reserved bits
7115
KVM_MSR_EXIT_REASON_FILTER access blocked by KVM_X86_SET_MSR_FILTER
7116
============================ ========================================
7118
For KVM_EXIT_X86_RDMSR, the "index" field tells userspace which MSR the guest
7119
wants to read. To respond to this request with a successful read, userspace
7120
writes the respective data into the "data" field and must continue guest
7121
execution to ensure the read data is transferred into guest register state.
7123
If the RDMSR request was unsuccessful, userspace indicates that with a "1" in
7124
the "error" field. This will inject a #GP into the guest when the VCPU is
7125
executed again.
7127
For KVM_EXIT_X86_WRMSR, the "index" field tells userspace which MSR the guest
7128
wants to write. Once finished processing the event, userspace must continue
7129
vCPU execution. If the MSR write was unsuccessful, userspace also sets the
7130
"error" field to "1".
7132
See KVM_X86_SET_MSR_FILTER for details on the interaction with MSR filtering.
7134
::
7137
struct kvm_xen_exit {
7138
#define KVM_EXIT_XEN_HCALL 1
7139
__u32 type;
7140
union {
7141
struct {
7142
__u32 longmode;
7143
__u32 cpl;
7144
__u64 input;
7145
__u64 result;
7146
__u64 params[6];
7147
} hcall;
7148
} u;
7149
};
7150
/* KVM_EXIT_XEN */
7151
struct kvm_hyperv_exit xen;
7153
Indicates that the VCPU exits into userspace to process some tasks
7154
related to Xen emulation.
7156
Valid values for 'type' are:
7158
- KVM_EXIT_XEN_HCALL -- synchronously notify user-space about Xen hypercall.
7159
Userspace is expected to place the hypercall result into the appropriate
7160
field before invoking KVM_RUN again.
7162
::
7164
/* KVM_EXIT_RISCV_SBI */
7165
struct {
7166
unsigned long extension_id;
7167
unsigned long function_id;
7168
unsigned long args[6];
7169
unsigned long ret[2];
7170
} riscv_sbi;
7172
If exit reason is KVM_EXIT_RISCV_SBI then it indicates that the VCPU has
7173
done a SBI call which is not handled by KVM RISC-V kernel module. The details
7174
of the SBI call are available in 'riscv_sbi' member of kvm_run structure. The
7175
'extension_id' field of 'riscv_sbi' represents SBI extension ID whereas the
7176
'function_id' field represents function ID of given SBI extension. The 'args'
7177
array field of 'riscv_sbi' represents parameters for the SBI call and 'ret'
7178
array field represents return values. The userspace should update the return
7179
values of SBI call before resuming the VCPU. For more details on RISC-V SBI
7180
spec refer, https://github.com/riscv/riscv-sbi-doc.
7182
::
7184
/* KVM_EXIT_MEMORY_FAULT */
7185
struct {
7186
#define KVM_MEMORY_EXIT_FLAG_PRIVATE (1ULL << 3)
7187
__u64 flags;
7188
__u64 gpa;
7189
__u64 size;
7190
} memory_fault;
7192
KVM_EXIT_MEMORY_FAULT indicates the vCPU has encountered a memory fault that
7193
could not be resolved by KVM. The 'gpa' and 'size' (in bytes) describe the
7194
guest physical address range [gpa, gpa + size) of the fault. The 'flags' field
7195
describes properties of the faulting access that are likely pertinent:
7197
- KVM_MEMORY_EXIT_FLAG_PRIVATE - When set, indicates the memory fault occurred
7198
on a private memory access. When clear, indicates the fault occurred on a
7199
shared access.
7201
Note! KVM_EXIT_MEMORY_FAULT is unique among all KVM exit reasons in that it
7202
accompanies a return code of '-1', not '0'! errno will always be set to EFAULT
7203
or EHWPOISON when KVM exits with KVM_EXIT_MEMORY_FAULT, userspace should assume
7204
kvm_run.exit_reason is stale/undefined for all other error numbers.
7206
::
7208
/* KVM_EXIT_NOTIFY */
7209
struct {
7210
#define KVM_NOTIFY_CONTEXT_INVALID (1 << 0)
7211
__u32 flags;
7212
} notify;
7214
Used on x86 systems. When the VM capability KVM_CAP_X86_NOTIFY_VMEXIT is
7215
enabled, a VM exit generated if no event window occurs in VM non-root mode
7216
for a specified amount of time. Once KVM_X86_NOTIFY_VMEXIT_USER is set when
7217
enabling the cap, it would exit to userspace with the exit reason
7218
KVM_EXIT_NOTIFY for further handling. The "flags" field contains more
7219
detailed info.
7221
The valid value for 'flags' is:
7223
- KVM_NOTIFY_CONTEXT_INVALID -- the VM context is corrupted and not valid
7224
in VMCS. It would run into unknown result if resume the target VM.
7226
::
7228
/* KVM_EXIT_TDX */
7229
struct {
7230
__u64 flags;
7231
__u64 nr;
7232
union {
7233
struct {
7234
u64 ret;
7235
u64 data[5];
7236
} unknown;
7237
struct {
7238
u64 ret;
7239
u64 gpa;
7240
u64 size;
7241
} get_quote;
7242
struct {
7243
u64 ret;
7244
u64 leaf;
7245
u64 r11, r12, r13, r14;
7246
} get_tdvmcall_info;
7247
struct {
7248
u64 ret;
7249
u64 vector;
7250
} setup_event_notify;
7251
};
7252
} tdx;
7254
Process a TDVMCALL from the guest. KVM forwards select TDVMCALL based
7255
on the Guest-Hypervisor Communication Interface (GHCI) specification;
7256
KVM bridges these requests to the userspace VMM with minimal changes,
7257
placing the inputs in the union and copying them back to the guest
7258
on re-entry.
7260
Flags are currently always zero, whereas ``nr`` contains the TDVMCALL
7261
number from register R11. The remaining field of the union provide the
7262
inputs and outputs of the TDVMCALL. Currently the following values of
7263
``nr`` are defined:
7265
* ``TDVMCALL_GET_QUOTE``: the guest has requested to generate a TD-Quote
7266
signed by a service hosting TD-Quoting Enclave operating on the host.
7267
Parameters and return value are in the ``get_quote`` field of the union.
7268
The ``gpa`` field and ``size`` specify the guest physical address
7269
(without the shared bit set) and the size of a shared-memory buffer, in
7270
which the TDX guest passes a TD Report. The ``ret`` field represents
7271
the return value of the GetQuote request. When the request has been
7272
queued successfully, the TDX guest can poll the status field in the
7273
shared-memory area to check whether the Quote generation is completed or
7274
not. When completed, the generated Quote is returned via the same buffer.
7276
* ``TDVMCALL_GET_TD_VM_CALL_INFO``: the guest has requested the support
7277
status of TDVMCALLs. The output values for the given leaf should be
7278
placed in fields from ``r11`` to ``r14`` of the ``get_tdvmcall_info``
7279
field of the union.
7281
* ``TDVMCALL_SETUP_EVENT_NOTIFY_INTERRUPT``: the guest has requested to
7282
set up a notification interrupt for vector ``vector``.
7284
KVM may add support for more values in the future that may cause a userspace
7285
exit, even without calls to ``KVM_ENABLE_CAP`` or similar. In this case,
7286
it will enter with output fields already valid; in the common case, the
7287
``unknown.ret`` field of the union will be ``TDVMCALL_STATUS_SUBFUNC_UNSUPPORTED``.
7288
Userspace need not do anything if it does not wish to support a TDVMCALL.
7289
::
7291
/* Fix the size of the union. */
7292
char padding[256];
7293
};
7295
/*
7296
* shared registers between kvm and userspace.
7297
* kvm_valid_regs specifies the register classes set by the host
7298
* kvm_dirty_regs specified the register classes dirtied by userspace
7299
* struct kvm_sync_regs is architecture specific, as well as the
7300
* bits for kvm_valid_regs and kvm_dirty_regs
7301
*/
7302
__u64 kvm_valid_regs;
7303
__u64 kvm_dirty_regs;
7304
union {
7305
struct kvm_sync_regs regs;
7306
char padding[SYNC_REGS_SIZE_BYTES];
7307
} s;
7309
If KVM_CAP_SYNC_REGS is defined, these fields allow userspace to access
7310
certain guest registers without having to call SET/GET_*REGS. Thus we can
7311
avoid some system call overhead if userspace has to handle the exit.
7312
Userspace can query the validity of the structure by checking
7313
kvm_valid_regs for specific bits. These bits are architecture specific
7314
and usually define the validity of a groups of registers. (e.g. one bit
7315
for general purpose registers)
7317
Please note that the kernel is allowed to use the kvm_run structure as the
7318
primary storage for certain register types. Therefore, the kernel may use the
7319
values in kvm_run even if the corresponding bit in kvm_dirty_regs is not set.
7322
.. _cap_enable:
7324
6. Capabilities that can be enabled on vCPUs
7325
============================================
7327
There are certain capabilities that change the behavior of the virtual CPU or
7328
the virtual machine when enabled. To enable them, please see
7329
:ref:`KVM_ENABLE_CAP`.
7331
Below you can find a list of capabilities and what their effect on the vCPU or
7332
the virtual machine is when enabling them.
7334
The following information is provided along with the description:
7336
Architectures:
7337
which instruction set architectures provide this ioctl.
7338
x86 includes both i386 and x86_64.
7340
Target:
7341
whether this is a per-vcpu or per-vm capability.
7343
Parameters:
7344
what parameters are accepted by the capability.
7346
Returns:
7347
the return value. General error numbers (EBADF, ENOMEM, EINVAL)
7348
are not detailed, but errors with specific meanings are.
7351
6.1 KVM_CAP_PPC_OSI
7352
-------------------
7354
:Architectures: ppc
7355
:Target: vcpu
7356
:Parameters: none
7357
:Returns: 0 on success; -1 on error
7359
This capability enables interception of OSI hypercalls that otherwise would
7360
be treated as normal system calls to be injected into the guest. OSI hypercalls
7361
were invented by Mac-on-Linux to have a standardized communication mechanism
7362
between the guest and the host.
7364
When this capability is enabled, KVM_EXIT_OSI can occur.
7367
6.2 KVM_CAP_PPC_PAPR
7368
--------------------
7370
:Architectures: ppc
7371
:Target: vcpu
7372
:Parameters: none
7373
:Returns: 0 on success; -1 on error
7375
This capability enables interception of PAPR hypercalls. PAPR hypercalls are
7376
done using the hypercall instruction "sc 1".
7378
It also sets the guest privilege level to "supervisor" mode. Usually the guest
7379
runs in "hypervisor" privilege mode with a few missing features.
7381
In addition to the above, it changes the semantics of SDR1. In this mode, the
7382
HTAB address part of SDR1 contains an HVA instead of a GPA, as PAPR keeps the
7383
HTAB invisible to the guest.
7385
When this capability is enabled, KVM_EXIT_PAPR_HCALL can occur.
7388
6.3 KVM_CAP_SW_TLB
7389
------------------
7391
:Architectures: ppc
7392
:Target: vcpu
7393
:Parameters: args[0] is the address of a struct kvm_config_tlb
7394
:Returns: 0 on success; -1 on error
7396
::
7398
struct kvm_config_tlb {
7399
__u64 params;
7400
__u64 array;
7401
__u32 mmu_type;
7402
__u32 array_len;
7403
};
7405
Configures the virtual CPU's TLB array, establishing a shared memory area
7406
between userspace and KVM. The "params" and "array" fields are userspace
7407
addresses of mmu-type-specific data structures. The "array_len" field is an
7408
safety mechanism, and should be set to the size in bytes of the memory that
7409
userspace has reserved for the array. It must be at least the size dictated
7410
by "mmu_type" and "params".
7412
While KVM_RUN is active, the shared region is under control of KVM. Its
7413
contents are undefined, and any modification by userspace results in
7414
boundedly undefined behavior.
7416
On return from KVM_RUN, the shared region will reflect the current state of
7417
the guest's TLB. If userspace makes any changes, it must call KVM_DIRTY_TLB
7418
to tell KVM which entries have been changed, prior to calling KVM_RUN again
7419
on this vcpu.
7421
For mmu types KVM_MMU_FSL_BOOKE_NOHV and KVM_MMU_FSL_BOOKE_HV:
7423
- The "params" field is of type "struct kvm_book3e_206_tlb_params".
7424
- The "array" field points to an array of type "struct
7425
kvm_book3e_206_tlb_entry".
7426
- The array consists of all entries in the first TLB, followed by all
7427
entries in the second TLB.
7428
- Within a TLB, entries are ordered first by increasing set number. Within a
7429
set, entries are ordered by way (increasing ESEL).
7430
- The hash for determining set number in TLB0 is: (MAS2 >> 12) & (num_sets - 1)
7431
where "num_sets" is the tlb_sizes[] value divided by the tlb_ways[] value.
7432
- The tsize field of mas1 shall be set to 4K on TLB0, even though the
7433
hardware ignores this value for TLB0.
7435
6.4 KVM_CAP_S390_CSS_SUPPORT
7436
----------------------------
7438
:Architectures: s390
7439
:Target: vcpu
7440
:Parameters: none
7441
:Returns: 0 on success; -1 on error
7443
This capability enables support for handling of channel I/O instructions.
7445
TEST PENDING INTERRUPTION and the interrupt portion of TEST SUBCHANNEL are
7446
handled in-kernel, while the other I/O instructions are passed to userspace.
7448
When this capability is enabled, KVM_EXIT_S390_TSCH will occur on TEST
7449
SUBCHANNEL intercepts.
7451
Note that even though this capability is enabled per-vcpu, the complete
7452
virtual machine is affected.
7454
6.5 KVM_CAP_PPC_EPR
7455
-------------------
7457
:Architectures: ppc
7458
:Target: vcpu
7459
:Parameters: args[0] defines whether the proxy facility is active
7460
:Returns: 0 on success; -1 on error
7462
This capability enables or disables the delivery of interrupts through the
7463
external proxy facility.
7465
When enabled (args[0] != 0), every time the guest gets an external interrupt
7466
delivered, it automatically exits into user space with a KVM_EXIT_EPR exit
7467
to receive the topmost interrupt vector.
7469
When disabled (args[0] == 0), behavior is as if this facility is unsupported.
7471
When this capability is enabled, KVM_EXIT_EPR can occur.
7473
6.6 KVM_CAP_IRQ_MPIC
7474
--------------------
7476
:Architectures: ppc
7477
:Parameters: args[0] is the MPIC device fd;
7478
args[1] is the MPIC CPU number for this vcpu
7480
This capability connects the vcpu to an in-kernel MPIC device.
7482
6.7 KVM_CAP_IRQ_XICS
7483
--------------------
7485
:Architectures: ppc
7486
:Target: vcpu
7487
:Parameters: args[0] is the XICS device fd;
7488
args[1] is the XICS CPU number (server ID) for this vcpu
7490
This capability connects the vcpu to an in-kernel XICS device.
7492
6.8 KVM_CAP_S390_IRQCHIP
7493
------------------------
7495
:Architectures: s390
7496
:Target: vm
7497
:Parameters: none
7499
This capability enables the in-kernel irqchip for s390. Please refer to
7500
"4.24 KVM_CREATE_IRQCHIP" for details.
7502
6.9 KVM_CAP_MIPS_FPU
7503
--------------------
7505
:Architectures: mips
7506
:Target: vcpu
7507
:Parameters: args[0] is reserved for future use (should be 0).
7509
This capability allows the use of the host Floating Point Unit by the guest. It
7510
allows the Config1.FP bit to be set to enable the FPU in the guest. Once this is
7511
done the ``KVM_REG_MIPS_FPR_*`` and ``KVM_REG_MIPS_FCR_*`` registers can be
7512
accessed (depending on the current guest FPU register mode), and the Status.FR,
7513
Config5.FRE bits are accessible via the KVM API and also from the guest,
7514
depending on them being supported by the FPU.
7516
6.10 KVM_CAP_MIPS_MSA
7517
---------------------
7519
:Architectures: mips
7520
:Target: vcpu
7521
:Parameters: args[0] is reserved for future use (should be 0).
7523
This capability allows the use of the MIPS SIMD Architecture (MSA) by the guest.
7524
It allows the Config3.MSAP bit to be set to enable the use of MSA by the guest.
7525
Once this is done the ``KVM_REG_MIPS_VEC_*`` and ``KVM_REG_MIPS_MSA_*``
7526
registers can be accessed, and the Config5.MSAEn bit is accessible via the
7527
KVM API and also from the guest.
7529
6.74 KVM_CAP_SYNC_REGS
7530
----------------------
7532
:Architectures: s390, x86
7533
:Target: s390: always enabled, x86: vcpu
7534
:Parameters: none
7535
:Returns: x86: KVM_CHECK_EXTENSION returns a bit-array indicating which register
7536
sets are supported
7537
(bitfields defined in arch/x86/include/uapi/asm/kvm.h).
7539
As described above in the kvm_sync_regs struct info in section :ref:`kvm_run`,
7540
KVM_CAP_SYNC_REGS "allow[s] userspace to access certain guest registers
7541
without having to call SET/GET_*REGS". This reduces overhead by eliminating
7542
repeated ioctl calls for setting and/or getting register values. This is
7543
particularly important when userspace is making synchronous guest state
7544
modifications, e.g. when emulating and/or intercepting instructions in
7545
userspace.
7547
For s390 specifics, please refer to the source code.
7549
For x86:
7551
- the register sets to be copied out to kvm_run are selectable
7552
by userspace (rather that all sets being copied out for every exit).
7553
- vcpu_events are available in addition to regs and sregs.
7555
For x86, the 'kvm_valid_regs' field of struct kvm_run is overloaded to
7556
function as an input bit-array field set by userspace to indicate the
7557
specific register sets to be copied out on the next exit.
7559
To indicate when userspace has modified values that should be copied into
7560
the vCPU, the all architecture bitarray field, 'kvm_dirty_regs' must be set.
7561
This is done using the same bitflags as for the 'kvm_valid_regs' field.
7562
If the dirty bit is not set, then the register set values will not be copied
7563
into the vCPU even if they've been modified.
7565
Unused bitfields in the bitarrays must be set to zero.
7567
::
7569
struct kvm_sync_regs {
7570
struct kvm_regs regs;
7571
struct kvm_sregs sregs;
7572
struct kvm_vcpu_events events;
7573
};
7575
6.75 KVM_CAP_PPC_IRQ_XIVE
7576
-------------------------
7578
:Architectures: ppc
7579
:Target: vcpu
7580
:Parameters: args[0] is the XIVE device fd;
7581
args[1] is the XIVE CPU number (server ID) for this vcpu
7583
This capability connects the vcpu to an in-kernel XIVE device.
7585
6.76 KVM_CAP_HYPERV_SYNIC
7586
-------------------------
7588
:Architectures: x86
7589
:Target: vcpu
7591
This capability, if KVM_CHECK_EXTENSION indicates that it is
7592
available, means that the kernel has an implementation of the
7593
Hyper-V Synthetic interrupt controller(SynIC). Hyper-V SynIC is
7594
used to support Windows Hyper-V based guest paravirt drivers(VMBus).
7596
In order to use SynIC, it has to be activated by setting this
7597
capability via KVM_ENABLE_CAP ioctl on the vcpu fd. Note that this
7598
will disable the use of APIC hardware virtualization even if supported
7599
by the CPU, as it's incompatible with SynIC auto-EOI behavior.
7601
6.77 KVM_CAP_HYPERV_SYNIC2
7602
--------------------------
7604
:Architectures: x86
7605
:Target: vcpu
7607
This capability enables a newer version of Hyper-V Synthetic interrupt
7608
controller (SynIC). The only difference with KVM_CAP_HYPERV_SYNIC is that KVM
7609
doesn't clear SynIC message and event flags pages when they are enabled by
7610
writing to the respective MSRs.
7612
6.78 KVM_CAP_HYPERV_DIRECT_TLBFLUSH
7613
-----------------------------------
7615
:Architectures: x86
7616
:Target: vcpu
7618
This capability indicates that KVM running on top of Hyper-V hypervisor
7619
enables Direct TLB flush for its guests meaning that TLB flush
7620
hypercalls are handled by Level 0 hypervisor (Hyper-V) bypassing KVM.
7621
Due to the different ABI for hypercall parameters between Hyper-V and
7622
KVM, enabling this capability effectively disables all hypercall
7623
handling by KVM (as some KVM hypercall may be mistakenly treated as TLB
7624
flush hypercalls by Hyper-V) so userspace should disable KVM identification
7625
in CPUID and only exposes Hyper-V identification. In this case, guest
7626
thinks it's running on Hyper-V and only use Hyper-V hypercalls.
7628
6.79 KVM_CAP_HYPERV_ENFORCE_CPUID
7629
---------------------------------
7631
:Architectures: x86
7632
:Target: vcpu
7634
When enabled, KVM will disable emulated Hyper-V features provided to the
7635
guest according to the bits Hyper-V CPUID feature leaves. Otherwise, all
7636
currently implemented Hyper-V features are provided unconditionally when
7637
Hyper-V identification is set in the HYPERV_CPUID_INTERFACE (0x40000001)
7638
leaf.
7640
6.80 KVM_CAP_ENFORCE_PV_FEATURE_CPUID
7641
-------------------------------------
7643
:Architectures: x86
7644
:Target: vcpu
7646
When enabled, KVM will disable paravirtual features provided to the
7647
guest according to the bits in the KVM_CPUID_FEATURES CPUID leaf
7648
(0x40000001). Otherwise, a guest may use the paravirtual features
7649
regardless of what has actually been exposed through the CPUID leaf.
7651
.. _KVM_CAP_DIRTY_LOG_RING:
7654
.. _cap_enable_vm:
7656
7. Capabilities that can be enabled on VMs
7657
==========================================
7659
There are certain capabilities that change the behavior of the virtual
7660
machine when enabled. To enable them, please see section
7661
:ref:`KVM_ENABLE_CAP`. Below you can find a list of capabilities and
7662
what their effect on the VM is when enabling them.
7664
The following information is provided along with the description:
7666
Architectures:
7667
which instruction set architectures provide this ioctl.
7668
x86 includes both i386 and x86_64.
7670
Parameters:
7671
what parameters are accepted by the capability.
7673
Returns:
7674
the return value. General error numbers (EBADF, ENOMEM, EINVAL)
7675
are not detailed, but errors with specific meanings are.
7678
7.1 KVM_CAP_PPC_ENABLE_HCALL
7679
----------------------------
7681
:Architectures: ppc
7682
:Parameters: args[0] is the sPAPR hcall number;
7683
args[1] is 0 to disable, 1 to enable in-kernel handling
7685
This capability controls whether individual sPAPR hypercalls (hcalls)
7686
get handled by the kernel or not. Enabling or disabling in-kernel
7687
handling of an hcall is effective across the VM. On creation, an
7688
initial set of hcalls are enabled for in-kernel handling, which
7689
consists of those hcalls for which in-kernel handlers were implemented
7690
before this capability was implemented. If disabled, the kernel will
7691
not to attempt to handle the hcall, but will always exit to userspace
7692
to handle it. Note that it may not make sense to enable some and
7693
disable others of a group of related hcalls, but KVM does not prevent
7694
userspace from doing that.
7696
If the hcall number specified is not one that has an in-kernel
7697
implementation, the KVM_ENABLE_CAP ioctl will fail with an EINVAL
7698
error.
7700
7.2 KVM_CAP_S390_USER_SIGP
7701
--------------------------
7703
:Architectures: s390
7704
:Parameters: none
7706
This capability controls which SIGP orders will be handled completely in user
7707
space. With this capability enabled, all fast orders will be handled completely
7708
in the kernel:
7710
- SENSE
7711
- SENSE RUNNING
7712
- EXTERNAL CALL
7713
- EMERGENCY SIGNAL
7714
- CONDITIONAL EMERGENCY SIGNAL
7716
All other orders will be handled completely in user space.
7718
Only privileged operation exceptions will be checked for in the kernel (or even
7719
in the hardware prior to interception). If this capability is not enabled, the
7720
old way of handling SIGP orders is used (partially in kernel and user space).
7722
7.3 KVM_CAP_S390_VECTOR_REGISTERS
7723
---------------------------------
7725
:Architectures: s390
7726
:Parameters: none
7727
:Returns: 0 on success, negative value on error
7729
Allows use of the vector registers introduced with z13 processor, and
7730
provides for the synchronization between host and user space. Will
7731
return -EINVAL if the machine does not support vectors.
7733
7.4 KVM_CAP_S390_USER_STSI
7734
--------------------------
7736
:Architectures: s390
7737
:Parameters: none
7739
This capability allows post-handlers for the STSI instruction. After
7740
initial handling in the kernel, KVM exits to user space with
7741
KVM_EXIT_S390_STSI to allow user space to insert further data.
7743
Before exiting to userspace, kvm handlers should fill in s390_stsi field of
7744
vcpu->run::
7746
struct {
7747
__u64 addr;
7748
__u8 ar;
7749
__u8 reserved;
7750
__u8 fc;
7751
__u8 sel1;
7752
__u16 sel2;
7753
} s390_stsi;
7755
@addr - guest address of STSI SYSIB
7756
@fc - function code
7757
@sel1 - selector 1
7758
@sel2 - selector 2
7759
@ar - access register number
7761
KVM handlers should exit to userspace with rc = -EREMOTE.
7763
7.5 KVM_CAP_SPLIT_IRQCHIP
7764
-------------------------
7766
:Architectures: x86
7767
:Parameters: args[0] - number of routes reserved for userspace IOAPICs
7768
:Returns: 0 on success, -1 on error
7770
Create a local apic for each processor in the kernel. This can be used
7771
instead of KVM_CREATE_IRQCHIP if the userspace VMM wishes to emulate the
7772
IOAPIC and PIC (and also the PIT, even though this has to be enabled
7773
separately).
7775
This capability also enables in kernel routing of interrupt requests;
7776
when KVM_CAP_SPLIT_IRQCHIP only routes of KVM_IRQ_ROUTING_MSI type are
7777
used in the IRQ routing table. The first args[0] MSI routes are reserved
7778
for the IOAPIC pins. Whenever the LAPIC receives an EOI for these routes,
7779
a KVM_EXIT_IOAPIC_EOI vmexit will be reported to userspace.
7781
Fails if VCPU has already been created, or if the irqchip is already in the
7782
kernel (i.e. KVM_CREATE_IRQCHIP has already been called).
7784
7.6 KVM_CAP_S390_RI
7785
-------------------
7787
:Architectures: s390
7788
:Parameters: none
7790
Allows use of runtime-instrumentation introduced with zEC12 processor.
7791
Will return -EINVAL if the machine does not support runtime-instrumentation.
7792
Will return -EBUSY if a VCPU has already been created.
7794
7.7 KVM_CAP_X2APIC_API
7795
----------------------
7797
:Architectures: x86
7798
:Parameters: args[0] - features that should be enabled
7799
:Returns: 0 on success, -EINVAL when args[0] contains invalid features
7801
Valid feature flags in args[0] are::
7803
#define KVM_X2APIC_API_USE_32BIT_IDS (1ULL << 0)
7804
#define KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK (1ULL << 1)
7805
#define KVM_X2APIC_ENABLE_SUPPRESS_EOI_BROADCAST (1ULL << 2)
7806
#define KVM_X2APIC_DISABLE_SUPPRESS_EOI_BROADCAST (1ULL << 3)
7808
Enabling KVM_X2APIC_API_USE_32BIT_IDS changes the behavior of
7809
KVM_SET_GSI_ROUTING, KVM_SIGNAL_MSI, KVM_SET_LAPIC, and KVM_GET_LAPIC,
7810
allowing the use of 32-bit APIC IDs. See KVM_CAP_X2APIC_API in their
7811
respective sections.
7813
KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK must be enabled for x2APIC to work
7814
in logical mode or with more than 255 VCPUs. Otherwise, KVM treats 0xff
7815
as a broadcast even in x2APIC mode in order to support physical x2APIC
7816
without interrupt remapping. This is undesirable in logical mode,
7817
where 0xff represents CPUs 0-7 in cluster 0.
7819
Setting KVM_X2APIC_ENABLE_SUPPRESS_EOI_BROADCAST instructs KVM to enable
7820
Suppress EOI Broadcasts. KVM will advertise support for Suppress EOI
7821
Broadcast to the guest and suppress LAPIC EOI broadcasts when the guest
7822
sets the Suppress EOI Broadcast bit in the SPIV register. This flag is
7823
supported only when using a split IRQCHIP.
7825
Setting KVM_X2APIC_DISABLE_SUPPRESS_EOI_BROADCAST disables support for
7826
Suppress EOI Broadcasts entirely, i.e. instructs KVM to NOT advertise
7827
support to the guest.
7829
Modern VMMs should either enable KVM_X2APIC_ENABLE_SUPPRESS_EOI_BROADCAST
7830
or KVM_X2APIC_DISABLE_SUPPRESS_EOI_BROADCAST. If not, legacy quirky
7831
behavior will be used by KVM: in split IRQCHIP mode, KVM will advertise
7832
support for Suppress EOI Broadcasts but not actually suppress EOI
7833
broadcasts; for in-kernel IRQCHIP mode, KVM will not advertise support for
7834
Suppress EOI Broadcasts.
7836
Setting both KVM_X2APIC_ENABLE_SUPPRESS_EOI_BROADCAST and
7837
KVM_X2APIC_DISABLE_SUPPRESS_EOI_BROADCAST will fail with an EINVAL error,
7838
as will setting KVM_X2APIC_ENABLE_SUPPRESS_EOI_BROADCAST without a split
7839
IRCHIP.
7841
7.8 KVM_CAP_S390_USER_INSTR0
7842
----------------------------
7844
:Architectures: s390
7845
:Parameters: none
7847
With this capability enabled, all illegal instructions 0x0000 (2 bytes) will
7848
be intercepted and forwarded to user space. User space can use this
7849
mechanism e.g. to realize 2-byte software breakpoints. The kernel will
7850
not inject an operating exception for these instructions, user space has
7851
to take care of that.
7853
This capability can be enabled dynamically even if VCPUs were already
7854
created and are running.
7856
7.9 KVM_CAP_S390_GS
7857
-------------------
7859
:Architectures: s390
7860
:Parameters: none
7861
:Returns: 0 on success; -EINVAL if the machine does not support
7862
guarded storage; -EBUSY if a VCPU has already been created.
7864
Allows use of guarded storage for the KVM guest.
7866
7.10 KVM_CAP_S390_AIS
7867
---------------------
7869
:Architectures: s390
7870
:Parameters: none
7872
Allow use of adapter-interruption suppression.
7873
:Returns: 0 on success; -EBUSY if a VCPU has already been created.
7875
7.11 KVM_CAP_PPC_SMT
7876
--------------------
7878
:Architectures: ppc
7879
:Parameters: vsmt_mode, flags
7881
Enabling this capability on a VM provides userspace with a way to set
7882
the desired virtual SMT mode (i.e. the number of virtual CPUs per
7883
virtual core). The virtual SMT mode, vsmt_mode, must be a power of 2
7884
between 1 and 8. On POWER8, vsmt_mode must also be no greater than
7885
the number of threads per subcore for the host. Currently flags must
7886
be 0. A successful call to enable this capability will result in
7887
vsmt_mode being returned when the KVM_CAP_PPC_SMT capability is
7888
subsequently queried for the VM. This capability is only supported by
7889
HV KVM, and can only be set before any VCPUs have been created.
7890
The KVM_CAP_PPC_SMT_POSSIBLE capability indicates which virtual SMT
7891
modes are available.
7893
7.12 KVM_CAP_PPC_FWNMI
7894
----------------------
7896
:Architectures: ppc
7897
:Parameters: none
7899
With this capability a machine check exception in the guest address
7900
space will cause KVM to exit the guest with NMI exit reason. This
7901
enables QEMU to build error log and branch to guest kernel registered
7902
machine check handling routine. Without this capability KVM will
7903
branch to guests' 0x200 interrupt vector.
7905
7.13 KVM_CAP_X86_DISABLE_EXITS
7906
------------------------------
7908
:Architectures: x86
7909
:Parameters: args[0] defines which exits are disabled
7910
:Returns: 0 on success, -EINVAL when args[0] contains invalid exits
7911
or if any vCPUs have already been created
7913
Valid bits in args[0] are::
7915
#define KVM_X86_DISABLE_EXITS_MWAIT (1 << 0)
7916
#define KVM_X86_DISABLE_EXITS_HLT (1 << 1)
7917
#define KVM_X86_DISABLE_EXITS_PAUSE (1 << 2)
7918
#define KVM_X86_DISABLE_EXITS_CSTATE (1 << 3)
7919
#define KVM_X86_DISABLE_EXITS_APERFMPERF (1 << 4)
7921
Enabling this capability on a VM provides userspace with a way to no
7922
longer intercept some instructions for improved latency in some
7923
workloads, and is suggested when vCPUs are associated to dedicated
7924
physical CPUs. More bits can be added in the future; userspace can
7925
just pass the KVM_CHECK_EXTENSION result to KVM_ENABLE_CAP to disable
7926
all such vmexits.
7928
Do not enable KVM_FEATURE_PV_UNHALT if you disable HLT exits.
7930
Virtualizing the ``IA32_APERF`` and ``IA32_MPERF`` MSRs requires more
7931
than just disabling APERF/MPERF exits. While both Intel and AMD
7932
document strict usage conditions for these MSRs--emphasizing that only
7933
the ratio of their deltas over a time interval (T0 to T1) is
7934
architecturally defined--simply passing through the MSRs can still
7935
produce an incorrect ratio.
7937
This erroneous ratio can occur if, between T0 and T1:
7939
1. The vCPU thread migrates between logical processors.
7940
2. Live migration or suspend/resume operations take place.
7941
3. Another task shares the vCPU's logical processor.
7942
4. C-states lower than C0 are emulated (e.g., via HLT interception).
7943
5. The guest TSC frequency doesn't match the host TSC frequency.
7945
Due to these complexities, KVM does not automatically associate this
7946
passthrough capability with the guest CPUID bit,
7947
``CPUID.6:ECX.APERFMPERF[bit 0]``. Userspace VMMs that deem this
7948
mechanism adequate for virtualizing the ``IA32_APERF`` and
7949
``IA32_MPERF`` MSRs must set the guest CPUID bit explicitly.
7952
7.14 KVM_CAP_S390_HPAGE_1M
7953
--------------------------
7955
:Architectures: s390
7956
:Parameters: none
7957
:Returns: 0 on success, -EINVAL if hpage module parameter was not set
7958
or cmma is enabled, or the VM has the KVM_VM_S390_UCONTROL
7959
flag set
7961
With this capability the KVM support for memory backing with 1m pages
7962
through hugetlbfs can be enabled for a VM. After the capability is
7963
enabled, cmma can't be enabled anymore and pfmfi and the storage key
7964
interpretation are disabled. If cmma has already been enabled or the
7965
hpage module parameter is not set to 1, -EINVAL is returned.
7967
While it is generally possible to create a huge page backed VM without
7968
this capability, the VM will not be able to run.
7970
7.15 KVM_CAP_MSR_PLATFORM_INFO
7971
------------------------------
7973
:Architectures: x86
7974
:Parameters: args[0] whether feature should be enabled or not
7976
With this capability, a guest may read the MSR_PLATFORM_INFO MSR. Otherwise,
7977
a #GP would be raised when the guest tries to access. Currently, this
7978
capability does not enable write permissions of this MSR for the guest.
7980
7.16 KVM_CAP_PPC_NESTED_HV
7981
--------------------------
7983
:Architectures: ppc
7984
:Parameters: none
7985
:Returns: 0 on success, -EINVAL when the implementation doesn't support
7986
nested-HV virtualization.
7988
HV-KVM on POWER9 and later systems allows for "nested-HV"
7989
virtualization, which provides a way for a guest VM to run guests that
7990
can run using the CPU's supervisor mode (privileged non-hypervisor
7991
state). Enabling this capability on a VM depends on the CPU having
7992
the necessary functionality and on the facility being enabled with a
7993
kvm-hv module parameter.
7995
7.17 KVM_CAP_EXCEPTION_PAYLOAD
7996
------------------------------
7998
:Architectures: x86
7999
:Parameters: args[0] whether feature should be enabled or not
8001
With this capability enabled, CR2 will not be modified prior to the
8002
emulated VM-exit when L1 intercepts a #PF exception that occurs in
8003
L2. Similarly, for kvm-intel only, DR6 will not be modified prior to
8004
the emulated VM-exit when L1 intercepts a #DB exception that occurs in
8005
L2. As a result, when KVM_GET_VCPU_EVENTS reports a pending #PF (or
8006
#DB) exception for L2, exception.has_payload will be set and the
8007
faulting address (or the new DR6 bits*) will be reported in the
8008
exception_payload field. Similarly, when userspace injects a #PF (or
8009
#DB) into L2 using KVM_SET_VCPU_EVENTS, it is expected to set
8010
exception.has_payload and to put the faulting address - or the new DR6
8011
bits\ [#]_ - in the exception_payload field.
8013
This capability also enables exception.pending in struct
8014
kvm_vcpu_events, which allows userspace to distinguish between pending
8015
and injected exceptions.
8018
.. [#] For the new DR6 bits, note that bit 16 is set iff the #DB exception
8019
will clear DR6.RTM.
8021
7.18 KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2
8022
--------------------------------------
8024
:Architectures: x86, arm64, mips
8025
:Parameters: args[0] whether feature should be enabled or not
8027
Valid flags are::
8029
#define KVM_DIRTY_LOG_MANUAL_PROTECT_ENABLE (1 << 0)
8030
#define KVM_DIRTY_LOG_INITIALLY_SET (1 << 1)
8032
With KVM_DIRTY_LOG_MANUAL_PROTECT_ENABLE is set, KVM_GET_DIRTY_LOG will not
8033
automatically clear and write-protect all pages that are returned as dirty.
8034
Rather, userspace will have to do this operation separately using
8035
KVM_CLEAR_DIRTY_LOG.
8037
At the cost of a slightly more complicated operation, this provides better
8038
scalability and responsiveness for two reasons. First,
8039
KVM_CLEAR_DIRTY_LOG ioctl can operate on a 64-page granularity rather
8040
than requiring to sync a full memslot; this ensures that KVM does not
8041
take spinlocks for an extended period of time. Second, in some cases a
8042
large amount of time can pass between a call to KVM_GET_DIRTY_LOG and
8043
userspace actually using the data in the page. Pages can be modified
8044
during this time, which is inefficient for both the guest and userspace:
8045
the guest will incur a higher penalty due to write protection faults,
8046
while userspace can see false reports of dirty pages. Manual reprotection
8047
helps reducing this time, improving guest performance and reducing the
8048
number of dirty log false positives.
8050
With KVM_DIRTY_LOG_INITIALLY_SET set, all the bits of the dirty bitmap
8051
will be initialized to 1 when created. This also improves performance because
8052
dirty logging can be enabled gradually in small chunks on the first call
8053
to KVM_CLEAR_DIRTY_LOG. KVM_DIRTY_LOG_INITIALLY_SET depends on
8054
KVM_DIRTY_LOG_MANUAL_PROTECT_ENABLE (it is also only available on
8055
x86 and arm64 for now).
8057
KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 was previously available under the name
8058
KVM_CAP_MANUAL_DIRTY_LOG_PROTECT, but the implementation had bugs that make
8059
it hard or impossible to use it correctly. The availability of
8060
KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 signals that those bugs are fixed.
8061
Userspace should not try to use KVM_CAP_MANUAL_DIRTY_LOG_PROTECT.
8063
7.19 KVM_CAP_PPC_SECURE_GUEST
8064
------------------------------
8066
:Architectures: ppc
8068
This capability indicates that KVM is running on a host that has
8069
ultravisor firmware and thus can support a secure guest. On such a
8070
system, a guest can ask the ultravisor to make it a secure guest,
8071
one whose memory is inaccessible to the host except for pages which
8072
are explicitly requested to be shared with the host. The ultravisor
8073
notifies KVM when a guest requests to become a secure guest, and KVM
8074
has the opportunity to veto the transition.
8076
If present, this capability can be enabled for a VM, meaning that KVM
8077
will allow the transition to secure guest mode. Otherwise KVM will
8078
veto the transition.
8080
7.20 KVM_CAP_HALT_POLL
8081
----------------------
8083
:Architectures: all
8084
:Target: VM
8085
:Parameters: args[0] is the maximum poll time in nanoseconds
8086
:Returns: 0 on success; -1 on error
8088
KVM_CAP_HALT_POLL overrides the kvm.halt_poll_ns module parameter to set the
8089
maximum halt-polling time for all vCPUs in the target VM. This capability can
8090
be invoked at any time and any number of times to dynamically change the
8091
maximum halt-polling time.
8093
See Documentation/virt/kvm/halt-polling.rst for more information on halt
8094
polling.
8096
7.21 KVM_CAP_X86_USER_SPACE_MSR
8097
-------------------------------
8099
:Architectures: x86
8100
:Target: VM
8101
:Parameters: args[0] contains the mask of KVM_MSR_EXIT_REASON_* events to report
8102
:Returns: 0 on success; -1 on error
8104
This capability allows userspace to intercept RDMSR and WRMSR instructions if
8105
access to an MSR is denied. By default, KVM injects #GP on denied accesses.
8107
When a guest requests to read or write an MSR, KVM may not implement all MSRs
8108
that are relevant to a respective system. It also does not differentiate by
8109
CPU type.
8111
To allow more fine grained control over MSR handling, userspace may enable
8112
this capability. With it enabled, MSR accesses that match the mask specified in
8113
args[0] and would trigger a #GP inside the guest will instead trigger
8114
KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR exit notifications. Userspace
8115
can then implement model specific MSR handling and/or user notifications
8116
to inform a user that an MSR was not emulated/virtualized by KVM.
8118
The valid mask flags are:
8120
============================ ===============================================
8121
KVM_MSR_EXIT_REASON_UNKNOWN intercept accesses to unknown (to KVM) MSRs
8122
KVM_MSR_EXIT_REASON_INVAL intercept accesses that are architecturally
8123
invalid according to the vCPU model and/or mode
8124
KVM_MSR_EXIT_REASON_FILTER intercept accesses that are denied by userspace
8125
via KVM_X86_SET_MSR_FILTER
8126
============================ ===============================================
8128
7.22 KVM_CAP_X86_BUS_LOCK_EXIT
8129
-------------------------------
8131
:Architectures: x86
8132
:Target: VM
8133
:Parameters: args[0] defines the policy used when bus locks detected in guest
8134
:Returns: 0 on success, -EINVAL when args[0] contains invalid bits
8136
Valid bits in args[0] are::
8138
#define KVM_BUS_LOCK_DETECTION_OFF (1 << 0)
8139
#define KVM_BUS_LOCK_DETECTION_EXIT (1 << 1)
8141
Enabling this capability on a VM provides userspace with a way to select a
8142
policy to handle the bus locks detected in guest. Userspace can obtain the
8143
supported modes from the result of KVM_CHECK_EXTENSION and define it through
8144
the KVM_ENABLE_CAP. The supported modes are mutually-exclusive.
8146
This capability allows userspace to force VM exits on bus locks detected in the
8147
guest, irrespective whether or not the host has enabled split-lock detection
8148
(which triggers an #AC exception that KVM intercepts). This capability is
8149
intended to mitigate attacks where a malicious/buggy guest can exploit bus
8150
locks to degrade the performance of the whole system.
8152
If KVM_BUS_LOCK_DETECTION_OFF is set, KVM doesn't force guest bus locks to VM
8153
exit, although the host kernel's split-lock #AC detection still applies, if
8154
enabled.
8156
If KVM_BUS_LOCK_DETECTION_EXIT is set, KVM enables a CPU feature that ensures
8157
bus locks in the guest trigger a VM exit, and KVM exits to userspace for all
8158
such VM exits, e.g. to allow userspace to throttle the offending guest and/or
8159
apply some other policy-based mitigation. When exiting to userspace, KVM sets
8160
KVM_RUN_X86_BUS_LOCK in vcpu-run->flags, and conditionally sets the exit_reason
8161
to KVM_EXIT_X86_BUS_LOCK.
8163
Due to differences in the underlying hardware implementation, the vCPU's RIP at
8164
the time of exit diverges between Intel and AMD. On Intel hosts, RIP points at
8165
the next instruction, i.e. the exit is trap-like. On AMD hosts, RIP points at
8166
the offending instruction, i.e. the exit is fault-like.
8168
Note! Detected bus locks may be coincident with other exits to userspace, i.e.
8169
KVM_RUN_X86_BUS_LOCK should be checked regardless of the primary exit reason if
8170
userspace wants to take action on all detected bus locks.
8172
7.23 KVM_CAP_PPC_DAWR1
8173
----------------------
8175
:Architectures: ppc
8176
:Parameters: none
8177
:Returns: 0 on success, -EINVAL when CPU doesn't support 2nd DAWR
8179
This capability can be used to check / enable 2nd DAWR feature provided
8180
by POWER10 processor.
8183
7.24 KVM_CAP_VM_COPY_ENC_CONTEXT_FROM
8184
-------------------------------------
8186
:Architectures: x86 SEV enabled
8187
:Type: vm
8188
:Parameters: args[0] is the fd of the source vm
8189
:Returns: 0 on success; ENOTTY on error
8191
This capability enables userspace to copy encryption context from the vm
8192
indicated by the fd to the vm this is called on.
8194
This is intended to support in-guest workloads scheduled by the host. This
8195
allows the in-guest workload to maintain its own NPTs and keeps the two vms
8196
from accidentally clobbering each other with interrupts and the like (separate
8197
APIC/MSRs/etc).
8199
7.25 KVM_CAP_SGX_ATTRIBUTE
8200
--------------------------
8202
:Architectures: x86
8203
:Target: VM
8204
:Parameters: args[0] is a file handle of a SGX attribute file in securityfs
8205
:Returns: 0 on success, -EINVAL if the file handle is invalid or if a requested
8206
attribute is not supported by KVM.
8208
KVM_CAP_SGX_ATTRIBUTE enables a userspace VMM to grant a VM access to one or
8209
more privileged enclave attributes. args[0] must hold a file handle to a valid
8210
SGX attribute file corresponding to an attribute that is supported/restricted
8211
by KVM (currently only PROVISIONKEY).
8213
The SGX subsystem restricts access to a subset of enclave attributes to provide
8214
additional security for an uncompromised kernel, e.g. use of the PROVISIONKEY
8215
is restricted to deter malware from using the PROVISIONKEY to obtain a stable
8216
system fingerprint. To prevent userspace from circumventing such restrictions
8217
by running an enclave in a VM, KVM prevents access to privileged attributes by
8218
default.
8220
See Documentation/arch/x86/sgx.rst for more details.
8222
7.27 KVM_CAP_EXIT_ON_EMULATION_FAILURE
8223
--------------------------------------
8225
:Architectures: x86
8226
:Parameters: args[0] whether the feature should be enabled or not
8228
When this capability is enabled, an emulation failure will result in an exit
8229
to userspace with KVM_INTERNAL_ERROR (except when the emulator was invoked
8230
to handle a VMware backdoor instruction). Furthermore, KVM will now provide up
8231
to 15 instruction bytes for any exit to userspace resulting from an emulation
8232
failure. When these exits to userspace occur use the emulation_failure struct
8233
instead of the internal struct. They both have the same layout, but the
8234
emulation_failure struct matches the content better. It also explicitly
8235
defines the 'flags' field which is used to describe the fields in the struct
8236
that are valid (ie: if KVM_INTERNAL_ERROR_EMULATION_FLAG_INSTRUCTION_BYTES is
8237
set in the 'flags' field then both 'insn_size' and 'insn_bytes' have valid data
8238
in them.)
8240
7.28 KVM_CAP_ARM_MTE
8241
--------------------
8243
:Architectures: arm64
8244
:Parameters: none
8246
This capability indicates that KVM (and the hardware) supports exposing the
8247
Memory Tagging Extensions (MTE) to the guest. It must also be enabled by the
8248
VMM before creating any VCPUs to allow the guest access. Note that MTE is only
8249
available to a guest running in AArch64 mode and enabling this capability will
8250
cause attempts to create AArch32 VCPUs to fail.
8252
When enabled the guest is able to access tags associated with any memory given
8253
to the guest. KVM will ensure that the tags are maintained during swap or
8254
hibernation of the host; however the VMM needs to manually save/restore the
8255
tags as appropriate if the VM is migrated.
8257
When this capability is enabled all memory in memslots must be mapped as
8258
``MAP_ANONYMOUS`` or with a RAM-based file mapping (``tmpfs``, ``memfd``),
8259
attempts to create a memslot with an invalid mmap will result in an
8260
-EINVAL return.
8262
When enabled the VMM may make use of the ``KVM_ARM_MTE_COPY_TAGS`` ioctl to
8263
perform a bulk copy of tags to/from the guest.
8265
7.29 KVM_CAP_VM_MOVE_ENC_CONTEXT_FROM
8266
-------------------------------------
8268
:Architectures: x86 SEV enabled
8269
:Type: vm
8270
:Parameters: args[0] is the fd of the source vm
8271
:Returns: 0 on success
8273
This capability enables userspace to migrate the encryption context from the VM
8274
indicated by the fd to the VM this is called on.
8276
This is intended to support intra-host migration of VMs between userspace VMMs,
8277
upgrading the VMM process without interrupting the guest.
8279
7.31 KVM_CAP_DISABLE_QUIRKS2
8280
----------------------------
8282
:Parameters: args[0] - set of KVM quirks to disable
8283
:Architectures: x86
8284
:Type: vm
8286
This capability, if enabled, will cause KVM to disable some behavior
8287
quirks.
8289
Calling KVM_CHECK_EXTENSION for this capability returns a bitmask of
8290
quirks that can be disabled in KVM.
8292
The argument to KVM_ENABLE_CAP for this capability is a bitmask of
8293
quirks to disable, and must be a subset of the bitmask returned by
8294
KVM_CHECK_EXTENSION.
8296
The valid bits in cap.args[0] are:
8298
=================================== ============================================
8299
KVM_X86_QUIRK_LINT0_REENABLED By default, the reset value for the LVT
8300
LINT0 register is 0x700 (APIC_MODE_EXTINT).
8301
When this quirk is disabled, the reset value
8302
is 0x10000 (APIC_LVT_MASKED).
8304
KVM_X86_QUIRK_CD_NW_CLEARED By default, KVM clears CR0.CD and CR0.NW on
8305
AMD CPUs to workaround buggy guest firmware
8306
that runs in perpetuity with CR0.CD, i.e.
8307
with caches in "no fill" mode.
8309
When this quirk is disabled, KVM does not
8310
change the value of CR0.CD and CR0.NW.
8312
KVM_X86_QUIRK_LAPIC_MMIO_HOLE By default, the MMIO LAPIC interface is
8313
available even when configured for x2APIC
8314
mode. When this quirk is disabled, KVM
8315
disables the MMIO LAPIC interface if the
8316
LAPIC is in x2APIC mode.
8318
KVM_X86_QUIRK_OUT_7E_INC_RIP By default, KVM pre-increments %rip before
8319
exiting to userspace for an OUT instruction
8320
to port 0x7e. When this quirk is disabled,
8321
KVM does not pre-increment %rip before
8322
exiting to userspace.
8324
KVM_X86_QUIRK_MISC_ENABLE_NO_MWAIT When this quirk is disabled, KVM sets
8325
CPUID.01H:ECX[bit 3] (MONITOR/MWAIT) if
8326
IA32_MISC_ENABLE[bit 18] (MWAIT) is set.
8327
Additionally, when this quirk is disabled,
8328
KVM clears CPUID.01H:ECX[bit 3] if
8329
IA32_MISC_ENABLE[bit 18] is cleared.
8331
KVM_X86_QUIRK_FIX_HYPERCALL_INSN By default, KVM rewrites guest
8332
VMMCALL/VMCALL instructions to match the
8333
vendor's hypercall instruction for the
8334
system. When this quirk is disabled, KVM
8335
will no longer rewrite invalid guest
8336
hypercall instructions. Executing the
8337
incorrect hypercall instruction will
8338
generate a #UD within the guest.
8340
KVM_X86_QUIRK_MWAIT_NEVER_UD_FAULTS By default, KVM emulates MONITOR/MWAIT (if
8341
they are intercepted) as NOPs regardless of
8342
whether or not MONITOR/MWAIT are supported
8343
according to guest CPUID. When this quirk
8344
is disabled and KVM_X86_DISABLE_EXITS_MWAIT
8345
is not set (MONITOR/MWAIT are intercepted),
8346
KVM will inject a #UD on MONITOR/MWAIT if
8347
they're unsupported per guest CPUID. Note,
8348
KVM will modify MONITOR/MWAIT support in
8349
guest CPUID on writes to MISC_ENABLE if
8350
KVM_X86_QUIRK_MISC_ENABLE_NO_MWAIT is
8351
disabled.
8353
KVM_X86_QUIRK_SLOT_ZAP_ALL By default, for KVM_X86_DEFAULT_VM VMs, KVM
8354
invalidates all SPTEs in all memslots and
8355
address spaces when a memslot is deleted or
8356
moved. When this quirk is disabled (or the
8357
VM type isn't KVM_X86_DEFAULT_VM), KVM only
8358
ensures the backing memory of the deleted
8359
or moved memslot isn't reachable, i.e KVM
8360
_may_ invalidate only SPTEs related to the
8361
memslot.
8363
KVM_X86_QUIRK_STUFF_FEATURE_MSRS By default, at vCPU creation, KVM sets the
8364
vCPU's MSR_IA32_PERF_CAPABILITIES (0x345),
8365
MSR_IA32_ARCH_CAPABILITIES (0x10a),
8366
MSR_PLATFORM_INFO (0xce), and all VMX MSRs
8367
(0x480..0x492) to the maximal capabilities
8368
supported by KVM. KVM also sets
8369
MSR_IA32_UCODE_REV (0x8b) to an arbitrary
8370
value (which is different for Intel vs.
8371
AMD). Lastly, when guest CPUID is set (by
8372
userspace), KVM modifies select VMX MSR
8373
fields to force consistency between guest
8374
CPUID and L2's effective ISA. When this
8375
quirk is disabled, KVM zeroes the vCPU's MSR
8376
values (with two exceptions, see below),
8377
i.e. treats the feature MSRs like CPUID
8378
leaves and gives userspace full control of
8379
the vCPU model definition. This quirk does
8380
not affect VMX MSRs CR0/CR4_FIXED1 (0x487
8381
and 0x489), as KVM does now allow them to
8382
be set by userspace (KVM sets them based on
8383
guest CPUID, for safety purposes).
8385
KVM_X86_QUIRK_IGNORE_GUEST_PAT By default, on Intel platforms, KVM ignores
8386
guest PAT and forces the effective memory
8387
type to WB in EPT. The quirk is not available
8388
on Intel platforms which are incapable of
8389
safely honoring guest PAT (i.e., without CPU
8390
self-snoop, KVM always ignores guest PAT and
8391
forces effective memory type to WB). It is
8392
also ignored on AMD platforms or, on Intel,
8393
when a VM has non-coherent DMA devices
8394
assigned; KVM always honors guest PAT in
8395
such case. The quirk is needed to avoid
8396
slowdowns on certain Intel Xeon platforms
8397
(e.g. ICX, SPR) where self-snoop feature is
8398
supported but UC is slow enough to cause
8399
issues with some older guests that use
8400
UC instead of WC to map the video RAM.
8401
Userspace can disable the quirk to honor
8402
guest PAT if it knows that there is no such
8403
guest software, for example if it does not
8404
expose a bochs graphics device (which is
8405
known to have had a buggy driver).
8407
KVM_X86_QUIRK_VMCS12_ALLOW_FREEZE_IN_SMM By default, KVM relaxes the consistency
8408
check for GUEST_IA32_DEBUGCTL in vmcs12
8409
to allow FREEZE_IN_SMM to be set. When
8410
this quirk is disabled, KVM requires this
8411
bit to be cleared. Note that the vmcs02
8412
bit is still completely controlled by the
8413
host, regardless of the quirk setting.
8414
=================================== ============================================
8416
7.32 KVM_CAP_MAX_VCPU_ID
8417
------------------------
8419
:Architectures: x86
8420
:Target: VM
8421
:Parameters: args[0] - maximum APIC ID value set for current VM
8422
:Returns: 0 on success, -EINVAL if args[0] is beyond KVM_MAX_VCPU_IDS
8423
supported in KVM or if it has been set.
8425
This capability allows userspace to specify maximum possible APIC ID
8426
assigned for current VM session prior to the creation of vCPUs, saving
8427
memory for data structures indexed by the APIC ID. Userspace is able
8428
to calculate the limit to APIC ID values from designated
8429
CPU topology.
8431
The value can be changed only until KVM_ENABLE_CAP is set to a nonzero
8432
value or until a vCPU is created. Upon creation of the first vCPU,
8433
if the value was set to zero or KVM_ENABLE_CAP was not invoked, KVM
8434
uses the return value of KVM_CHECK_EXTENSION(KVM_CAP_MAX_VCPU_ID) as
8435
the maximum APIC ID.
8437
7.33 KVM_CAP_X86_NOTIFY_VMEXIT
8438
------------------------------
8440
:Architectures: x86
8441
:Target: VM
8442
:Parameters: args[0] is the value of notify window as well as some flags
8443
:Returns: 0 on success, -EINVAL if args[0] contains invalid flags or notify
8444
VM exit is unsupported.
8446
Bits 63:32 of args[0] are used for notify window.
8447
Bits 31:0 of args[0] are for some flags. Valid bits are::
8449
#define KVM_X86_NOTIFY_VMEXIT_ENABLED (1 << 0)
8450
#define KVM_X86_NOTIFY_VMEXIT_USER (1 << 1)
8452
This capability allows userspace to configure the notify VM exit on/off
8453
in per-VM scope during VM creation. Notify VM exit is disabled by default.
8454
When userspace sets KVM_X86_NOTIFY_VMEXIT_ENABLED bit in args[0], VMM will
8455
enable this feature with the notify window provided, which will generate
8456
a VM exit if no event window occurs in VM non-root mode for a specified of
8457
time (notify window).
8459
If KVM_X86_NOTIFY_VMEXIT_USER is set in args[0], upon notify VM exits happen,
8460
KVM would exit to userspace for handling.
8462
This capability is aimed to mitigate the threat that malicious VMs can
8463
cause CPU stuck (due to event windows don't open up) and make the CPU
8464
unavailable to host or other VMs.
8466
7.35 KVM_CAP_X86_APIC_BUS_CYCLES_NS
8467
-----------------------------------
8469
:Architectures: x86
8470
:Target: VM
8471
:Parameters: args[0] is the desired APIC bus clock rate, in nanoseconds
8472
:Returns: 0 on success, -EINVAL if args[0] contains an invalid value for the
8473
frequency or if any vCPUs have been created, -ENXIO if a virtual
8474
local APIC has not been created using KVM_CREATE_IRQCHIP.
8476
This capability sets the VM's APIC bus clock frequency, used by KVM's in-kernel
8477
virtual APIC when emulating APIC timers. KVM's default value can be retrieved
8478
by KVM_CHECK_EXTENSION.
8480
Note: Userspace is responsible for correctly configuring CPUID 0x15, a.k.a. the
8481
core crystal clock frequency, if a non-zero CPUID 0x15 is exposed to the guest.
8483
7.36 KVM_CAP_DIRTY_LOG_RING/KVM_CAP_DIRTY_LOG_RING_ACQ_REL
8484
----------------------------------------------------------
8486
:Architectures: x86, arm64, riscv
8487
:Type: vm
8488
:Parameters: args[0] - size of the dirty log ring
8490
KVM is capable of tracking dirty memory using ring buffers that are
8491
mmapped into userspace; there is one dirty ring per vcpu.
8493
The dirty ring is available to userspace as an array of
8494
``struct kvm_dirty_gfn``. Each dirty entry is defined as::
8496
struct kvm_dirty_gfn {
8497
__u32 flags;
8498
__u32 slot; /* as_id | slot_id */
8499
__u64 offset;
8500
};
8502
The following values are defined for the flags field to define the
8503
current state of the entry::
8505
#define KVM_DIRTY_GFN_F_DIRTY BIT(0)
8506
#define KVM_DIRTY_GFN_F_RESET BIT(1)
8507
#define KVM_DIRTY_GFN_F_MASK 0x3
8509
Userspace should call KVM_ENABLE_CAP ioctl right after KVM_CREATE_VM
8510
ioctl to enable this capability for the new guest and set the size of
8511
the rings. Enabling the capability is only allowed before creating any
8512
vCPU, and the size of the ring must be a power of two. The larger the
8513
ring buffer, the less likely the ring is full and the VM is forced to
8514
exit to userspace. The optimal size depends on the workload, but it is
8515
recommended that it be at least 64 KiB (4096 entries).
8517
Just like for dirty page bitmaps, the buffer tracks writes to
8518
all user memory regions for which the KVM_MEM_LOG_DIRTY_PAGES flag was
8519
set in KVM_SET_USER_MEMORY_REGION. Once a memory region is registered
8520
with the flag set, userspace can start harvesting dirty pages from the
8521
ring buffer.
8523
An entry in the ring buffer can be unused (flag bits ``00``),
8524
dirty (flag bits ``01``) or harvested (flag bits ``1X``). The
8525
state machine for the entry is as follows::
8527
dirtied harvested reset
8528
00 -----------> 01 -------------> 1X -------+
8529
^ |
8530
| |
8531
+------------------------------------------+
8533
To harvest the dirty pages, userspace accesses the mmapped ring buffer
8534
to read the dirty GFNs. If the flags has the DIRTY bit set (at this stage
8535
the RESET bit must be cleared), then it means this GFN is a dirty GFN.
8536
The userspace should harvest this GFN and mark the flags from state
8537
``01b`` to ``1Xb`` (bit 0 will be ignored by KVM, but bit 1 must be set
8538
to show that this GFN is harvested and waiting for a reset), and move
8539
on to the next GFN. The userspace should continue to do this until the
8540
flags of a GFN have the DIRTY bit cleared, meaning that it has harvested
8541
all the dirty GFNs that were available.
8543
Note that on weakly ordered architectures, userspace accesses to the
8544
ring buffer (and more specifically the 'flags' field) must be ordered,
8545
using load-acquire/store-release accessors when available, or any
8546
other memory barrier that will ensure this ordering.
8548
It's not necessary for userspace to harvest the all dirty GFNs at once.
8549
However it must collect the dirty GFNs in sequence, i.e., the userspace
8550
program cannot skip one dirty GFN to collect the one next to it.
8552
After processing one or more entries in the ring buffer, userspace
8553
calls the VM ioctl KVM_RESET_DIRTY_RINGS to notify the kernel about
8554
it, so that the kernel will reprotect those collected GFNs.
8555
Therefore, the ioctl must be called *before* reading the content of
8556
the dirty pages.
8558
The dirty ring can get full. When it happens, the KVM_RUN of the
8559
vcpu will return with exit reason KVM_EXIT_DIRTY_LOG_FULL.
8561
The dirty ring interface has a major difference comparing to the
8562
KVM_GET_DIRTY_LOG interface in that, when reading the dirty ring from
8563
userspace, it's still possible that the kernel has not yet flushed the
8564
processor's dirty page buffers into the kernel buffer (with dirty bitmaps, the
8565
flushing is done by the KVM_GET_DIRTY_LOG ioctl). To achieve that, one
8566
needs to kick the vcpu out of KVM_RUN using a signal. The resulting
8567
vmexit ensures that all dirty GFNs are flushed to the dirty rings.
8569
NOTE: KVM_CAP_DIRTY_LOG_RING_ACQ_REL is the only capability that
8570
should be exposed by weakly ordered architecture, in order to indicate
8571
the additional memory ordering requirements imposed on userspace when
8572
reading the state of an entry and mutating it from DIRTY to HARVESTED.
8573
Architecture with TSO-like ordering (such as x86) are allowed to
8574
expose both KVM_CAP_DIRTY_LOG_RING and KVM_CAP_DIRTY_LOG_RING_ACQ_REL
8575
to userspace.
8577
After enabling the dirty rings, the userspace needs to detect the
8578
capability of KVM_CAP_DIRTY_LOG_RING_WITH_BITMAP to see whether the
8579
ring structures can be backed by per-slot bitmaps. With this capability
8580
advertised, it means the architecture can dirty guest pages without
8581
vcpu/ring context, so that some of the dirty information will still be
8582
maintained in the bitmap structure. KVM_CAP_DIRTY_LOG_RING_WITH_BITMAP
8583
can't be enabled if the capability of KVM_CAP_DIRTY_LOG_RING_ACQ_REL
8584
hasn't been enabled, or any memslot has been existing.
8586
Note that the bitmap here is only a backup of the ring structure. The
8587
use of the ring and bitmap combination is only beneficial if there is
8588
only a very small amount of memory that is dirtied out of vcpu/ring
8589
context. Otherwise, the stand-alone per-slot bitmap mechanism needs to
8590
be considered.
8592
To collect dirty bits in the backup bitmap, userspace can use the same
8593
KVM_GET_DIRTY_LOG ioctl. KVM_CLEAR_DIRTY_LOG isn't needed as long as all
8594
the generation of the dirty bits is done in a single pass. Collecting
8595
the dirty bitmap should be the very last thing that the VMM does before
8596
considering the state as complete. VMM needs to ensure that the dirty
8597
state is final and avoid missing dirty pages from another ioctl ordered
8598
after the bitmap collection.
8600
NOTE: Multiple examples of using the backup bitmap: (1) save vgic/its
8601
tables through command KVM_DEV_ARM_{VGIC_GRP_CTRL, ITS_SAVE_TABLES} on
8602
KVM device "kvm-arm-vgic-its". (2) restore vgic/its tables through
8603
command KVM_DEV_ARM_{VGIC_GRP_CTRL, ITS_RESTORE_TABLES} on KVM device
8604
"kvm-arm-vgic-its". VGICv3 LPI pending status is restored. (3) save
8605
vgic3 pending table through KVM_DEV_ARM_VGIC_{GRP_CTRL, SAVE_PENDING_TABLES}
8606
command on KVM device "kvm-arm-vgic-v3".
8608
7.37 KVM_CAP_PMU_CAPABILITY
8609
---------------------------
8611
:Architectures: x86
8612
:Type: vm
8613
:Parameters: arg[0] is bitmask of PMU virtualization capabilities.
8614
:Returns: 0 on success, -EINVAL when arg[0] contains invalid bits
8616
This capability alters PMU virtualization in KVM.
8618
Calling KVM_CHECK_EXTENSION for this capability returns a bitmask of
8619
PMU virtualization capabilities that can be adjusted on a VM.
8621
The argument to KVM_ENABLE_CAP is also a bitmask and selects specific
8622
PMU virtualization capabilities to be applied to the VM. This can
8623
only be invoked on a VM prior to the creation of VCPUs.
8625
At this time, KVM_PMU_CAP_DISABLE is the only capability. Setting
8626
this capability will disable PMU virtualization for that VM. Usermode
8627
should adjust CPUID leaf 0xA to reflect that the PMU is disabled.
8629
7.38 KVM_CAP_VM_DISABLE_NX_HUGE_PAGES
8630
-------------------------------------
8632
:Architectures: x86
8633
:Type: vm
8634
:Parameters: arg[0] must be 0.
8635
:Returns: 0 on success, -EPERM if the userspace process does not
8636
have CAP_SYS_BOOT, -EINVAL if args[0] is not 0 or any vCPUs have been
8637
created.
8639
This capability disables the NX huge pages mitigation for iTLB MULTIHIT.
8641
The capability has no effect if the nx_huge_pages module parameter is not set.
8643
This capability may only be set before any vCPUs are created.
8645
7.39 KVM_CAP_ARM_EAGER_SPLIT_CHUNK_SIZE
8646
---------------------------------------
8648
:Architectures: arm64
8649
:Type: vm
8650
:Parameters: arg[0] is the new split chunk size.
8651
:Returns: 0 on success, -EINVAL if any memslot was already created.
8653
This capability sets the chunk size used in Eager Page Splitting.
8655
Eager Page Splitting improves the performance of dirty-logging (used
8656
in live migrations) when guest memory is backed by huge-pages. It
8657
avoids splitting huge-pages (into PAGE_SIZE pages) on fault, by doing
8658
it eagerly when enabling dirty logging (with the
8659
KVM_MEM_LOG_DIRTY_PAGES flag for a memory region), or when using
8660
KVM_CLEAR_DIRTY_LOG.
8662
The chunk size specifies how many pages to break at a time, using a
8663
single allocation for each chunk. Bigger the chunk size, more pages
8664
need to be allocated ahead of time.
8666
The chunk size needs to be a valid block size. The list of acceptable
8667
block sizes is exposed in KVM_CAP_ARM_SUPPORTED_BLOCK_SIZES as a
8668
64-bit bitmap (each bit describing a block size). The default value is
8669
0, to disable the eager page splitting.
8671
7.40 KVM_CAP_EXIT_HYPERCALL
8672
---------------------------
8674
:Architectures: x86
8675
:Type: vm
8677
This capability, if enabled, will cause KVM to exit to userspace
8678
with KVM_EXIT_HYPERCALL exit reason to process some hypercalls.
8680
Calling KVM_CHECK_EXTENSION for this capability will return a bitmask
8681
of hypercalls that can be configured to exit to userspace.
8682
Right now, the only such hypercall is KVM_HC_MAP_GPA_RANGE.
8684
The argument to KVM_ENABLE_CAP is also a bitmask, and must be a subset
8685
of the result of KVM_CHECK_EXTENSION. KVM will forward to userspace
8686
the hypercalls whose corresponding bit is in the argument, and return
8687
ENOSYS for the others.
8689
7.41 KVM_CAP_ARM_SYSTEM_SUSPEND
8690
-------------------------------
8692
:Architectures: arm64
8693
:Type: vm
8695
When enabled, KVM will exit to userspace with KVM_EXIT_SYSTEM_EVENT of
8696
type KVM_SYSTEM_EVENT_SUSPEND to process the guest suspend request.
8698
7.42 KVM_CAP_ARM_WRITABLE_IMP_ID_REGS
8699
-------------------------------------
8701
:Architectures: arm64
8702
:Target: VM
8703
:Parameters: None
8704
:Returns: 0 on success, -EINVAL if vCPUs have been created before enabling this
8705
capability.
8707
This capability changes the behavior of the registers that identify a PE
8708
implementation of the Arm architecture: MIDR_EL1, REVIDR_EL1, and AIDR_EL1.
8709
By default, these registers are visible to userspace but treated as invariant.
8711
When this capability is enabled, KVM allows userspace to change the
8712
aforementioned registers before the first KVM_RUN. These registers are VM
8713
scoped, meaning that the same set of values are presented on all vCPUs in a
8714
given VM.
8716
7.43 KVM_CAP_RISCV_MP_STATE_RESET
8717
---------------------------------
8719
:Architectures: riscv
8720
:Type: VM
8721
:Parameters: None
8722
:Returns: 0 on success, -EINVAL if arg[0] is not zero
8724
When this capability is enabled, KVM resets the VCPU when setting
8725
MP_STATE_INIT_RECEIVED through IOCTL. The original MP_STATE is preserved.
8727
7.43 KVM_CAP_ARM_CACHEABLE_PFNMAP_SUPPORTED
8728
-------------------------------------------
8730
:Architectures: arm64
8731
:Target: VM
8732
:Parameters: None
8734
This capability indicate to the userspace whether a PFNMAP memory region
8735
can be safely mapped as cacheable. This relies on the presence of
8736
force write back (FWB) feature support on the hardware.
8738
8. Other capabilities.
8739
======================
8741
This section lists capabilities that give information about other
8742
features of the KVM implementation.
8744
8.1 KVM_CAP_PPC_HWRNG
8745
---------------------
8747
:Architectures: ppc
8749
This capability, if KVM_CHECK_EXTENSION indicates that it is
8750
available, means that the kernel has an implementation of the
8751
H_RANDOM hypercall backed by a hardware random-number generator.
8752
If present, the kernel H_RANDOM handler can be enabled for guest use
8753
with the KVM_CAP_PPC_ENABLE_HCALL capability.
8755
8.3 KVM_CAP_PPC_MMU_RADIX
8756
-------------------------
8758
:Architectures: ppc
8760
This capability, if KVM_CHECK_EXTENSION indicates that it is
8761
available, means that the kernel can support guests using the
8762
radix MMU defined in Power ISA V3.00 (as implemented in the POWER9
8763
processor).
8765
8.4 KVM_CAP_PPC_MMU_HASH_V3
8766
---------------------------
8768
:Architectures: ppc
8770
This capability, if KVM_CHECK_EXTENSION indicates that it is
8771
available, means that the kernel can support guests using the
8772
hashed page table MMU defined in Power ISA V3.00 (as implemented in
8773
the POWER9 processor), including in-memory segment tables.
8775
8.5 KVM_CAP_MIPS_VZ
8776
-------------------
8778
:Architectures: mips
8780
This capability, if KVM_CHECK_EXTENSION on the main kvm handle indicates that
8781
it is available, means that full hardware assisted virtualization capabilities
8782
of the hardware are available for use through KVM. An appropriate
8783
KVM_VM_MIPS_* type must be passed to KVM_CREATE_VM to create a VM which
8784
utilises it.
8786
If KVM_CHECK_EXTENSION on a kvm VM handle indicates that this capability is
8787
available, it means that the VM is using full hardware assisted virtualization
8788
capabilities of the hardware. This is useful to check after creating a VM with
8789
KVM_VM_MIPS_DEFAULT.
8791
The value returned by KVM_CHECK_EXTENSION should be compared against known
8792
values (see below). All other values are reserved. This is to allow for the
8793
possibility of other hardware assisted virtualization implementations which
8794
may be incompatible with the MIPS VZ ASE.
8796
== ==========================================================================
8797
0 The trap & emulate implementation is in use to run guest code in user
8798
mode. Guest virtual memory segments are rearranged to fit the guest in the
8799
user mode address space.
8801
1 The MIPS VZ ASE is in use, providing full hardware assisted
8802
virtualization, including standard guest virtual memory segments.
8803
== ==========================================================================
8805
8.7 KVM_CAP_MIPS_64BIT
8806
----------------------
8808
:Architectures: mips
8810
This capability indicates the supported architecture type of the guest, i.e. the
8811
supported register and address width.
8813
The values returned when this capability is checked by KVM_CHECK_EXTENSION on a
8814
kvm VM handle correspond roughly to the CP0_Config.AT register field, and should
8815
be checked specifically against known values (see below). All other values are
8816
reserved.
8818
== ========================================================================
8819
0 MIPS32 or microMIPS32.
8820
Both registers and addresses are 32-bits wide.
8821
It will only be possible to run 32-bit guest code.
8823
1 MIPS64 or microMIPS64 with access only to 32-bit compatibility segments.
8824
Registers are 64-bits wide, but addresses are 32-bits wide.
8825
64-bit guest code may run but cannot access MIPS64 memory segments.
8826
It will also be possible to run 32-bit guest code.
8828
2 MIPS64 or microMIPS64 with access to all address segments.
8829
Both registers and addresses are 64-bits wide.
8830
It will be possible to run 64-bit or 32-bit guest code.
8831
== ========================================================================
8833
8.9 KVM_CAP_ARM_USER_IRQ
8834
------------------------
8836
:Architectures: arm64
8838
This capability, if KVM_CHECK_EXTENSION indicates that it is available, means
8839
that if userspace creates a VM without an in-kernel interrupt controller, it
8840
will be notified of changes to the output level of in-kernel emulated devices,
8841
which can generate virtual interrupts, presented to the VM.
8842
For such VMs, on every return to userspace, the kernel
8843
updates the vcpu's run->s.regs.device_irq_level field to represent the actual
8844
output level of the device.
8846
Whenever kvm detects a change in the device output level, kvm guarantees at
8847
least one return to userspace before running the VM. This exit could either
8848
be a KVM_EXIT_INTR or any other exit event, like KVM_EXIT_MMIO. This way,
8849
userspace can always sample the device output level and re-compute the state of
8850
the userspace interrupt controller. Userspace should always check the state
8851
of run->s.regs.device_irq_level on every kvm exit.
8852
The value in run->s.regs.device_irq_level can represent both level and edge
8853
triggered interrupt signals, depending on the device. Edge triggered interrupt
8854
signals will exit to userspace with the bit in run->s.regs.device_irq_level
8855
set exactly once per edge signal.
8857
The field run->s.regs.device_irq_level is available independent of
8858
run->kvm_valid_regs or run->kvm_dirty_regs bits.
8860
If KVM_CAP_ARM_USER_IRQ is supported, the KVM_CHECK_EXTENSION ioctl returns a
8861
number larger than 0 indicating the version of this capability is implemented
8862
and thereby which bits in run->s.regs.device_irq_level can signal values.
8864
Currently the following bits are defined for the device_irq_level bitmap::
8866
KVM_CAP_ARM_USER_IRQ >= 1:
8868
KVM_ARM_DEV_EL1_VTIMER - EL1 virtual timer
8869
KVM_ARM_DEV_EL1_PTIMER - EL1 physical timer
8870
KVM_ARM_DEV_PMU - ARM PMU overflow interrupt signal
8872
Future versions of kvm may implement additional events. These will get
8873
indicated by returning a higher number from KVM_CHECK_EXTENSION and will be
8874
listed above.
8876
8.10 KVM_CAP_PPC_SMT_POSSIBLE
8877
-----------------------------
8879
:Architectures: ppc
8881
Querying this capability returns a bitmap indicating the possible
8882
virtual SMT modes that can be set using KVM_CAP_PPC_SMT. If bit N
8883
(counting from the right) is set, then a virtual SMT mode of 2^N is
8884
available.
8886
8.12 KVM_CAP_HYPERV_VP_INDEX
8887
----------------------------
8889
:Architectures: x86
8891
This capability indicates that userspace can load HV_X64_MSR_VP_INDEX msr. Its
8892
value is used to denote the target vcpu for a SynIC interrupt. For
8893
compatibility, KVM initializes this msr to KVM's internal vcpu index. When this
8894
capability is absent, userspace can still query this msr's value.
8896
8.13 KVM_CAP_S390_AIS_MIGRATION
8897
-------------------------------
8899
:Architectures: s390
8901
This capability indicates if the flic device will be able to get/set the
8902
AIS states for migration via the KVM_DEV_FLIC_AISM_ALL attribute and allows
8903
to discover this without having to create a flic device.
8905
8.14 KVM_CAP_S390_PSW
8906
---------------------
8908
:Architectures: s390
8910
This capability indicates that the PSW is exposed via the kvm_run structure.
8912
8.15 KVM_CAP_S390_GMAP
8913
----------------------
8915
:Architectures: s390
8917
This capability indicates that the user space memory used as guest mapping can
8918
be anywhere in the user memory address space, as long as the memory slots are
8919
aligned and sized to a segment (1MB) boundary.
8921
8.16 KVM_CAP_S390_COW
8922
---------------------
8924
:Architectures: s390
8926
This capability indicates that the user space memory used as guest mapping can
8927
use copy-on-write semantics as well as dirty pages tracking via read-only page
8928
tables.
8930
8.17 KVM_CAP_S390_BPB
8931
---------------------
8933
:Architectures: s390
8935
This capability indicates that kvm will implement the interfaces to handle
8936
reset, migration and nested KVM for branch prediction blocking. The stfle
8937
facility 82 should not be provided to the guest without this capability.
8939
8.18 KVM_CAP_HYPERV_TLBFLUSH
8940
----------------------------
8942
:Architectures: x86
8944
This capability indicates that KVM supports paravirtualized Hyper-V TLB Flush
8945
hypercalls:
8946
HvFlushVirtualAddressSpace, HvFlushVirtualAddressSpaceEx,
8947
HvFlushVirtualAddressList, HvFlushVirtualAddressListEx.
8949
8.19 KVM_CAP_ARM_INJECT_SERROR_ESR
8950
----------------------------------
8952
:Architectures: arm64
8954
This capability indicates that userspace can specify (via the
8955
KVM_SET_VCPU_EVENTS ioctl) the syndrome value reported to the guest when it
8956
takes a virtual SError interrupt exception.
8957
If KVM advertises this capability, userspace can only specify the ISS field for
8958
the ESR syndrome. Other parts of the ESR, such as the EC are generated by the
8959
CPU when the exception is taken. If this virtual SError is taken to EL1 using
8960
AArch64, this value will be reported in the ISS field of ESR_ELx.
8962
See KVM_CAP_VCPU_EVENTS for more details.
8964
8.20 KVM_CAP_HYPERV_SEND_IPI
8965
----------------------------
8967
:Architectures: x86
8969
This capability indicates that KVM supports paravirtualized Hyper-V IPI send
8970
hypercalls:
8971
HvCallSendSyntheticClusterIpi, HvCallSendSyntheticClusterIpiEx.
8973
8.22 KVM_CAP_S390_VCPU_RESETS
8974
-----------------------------
8976
:Architectures: s390
8978
This capability indicates that the KVM_S390_NORMAL_RESET and
8979
KVM_S390_CLEAR_RESET ioctls are available.
8981
8.23 KVM_CAP_S390_PROTECTED
8982
---------------------------
8984
:Architectures: s390
8986
This capability indicates that the Ultravisor has been initialized and
8987
KVM can therefore start protected VMs.
8988
This capability governs the KVM_S390_PV_COMMAND ioctl and the
8989
KVM_MP_STATE_LOAD MP_STATE. KVM_SET_MP_STATE can fail for protected
8990
guests when the state change is invalid.
8992
8.24 KVM_CAP_STEAL_TIME
8993
-----------------------
8995
:Architectures: arm64, x86
8997
This capability indicates that KVM supports steal time accounting.
8998
When steal time accounting is supported it may be enabled with
8999
architecture-specific interfaces. This capability and the architecture-
9000
specific interfaces must be consistent, i.e. if one says the feature
9001
is supported, than the other should as well and vice versa. For arm64
9002
see Documentation/virt/kvm/devices/vcpu.rst "KVM_ARM_VCPU_PVTIME_CTRL".
9003
For x86 see Documentation/virt/kvm/x86/msr.rst "MSR_KVM_STEAL_TIME".
9005
8.25 KVM_CAP_S390_DIAG318
9006
-------------------------
9008
:Architectures: s390
9010
This capability enables a guest to set information about its control program
9011
(i.e. guest kernel type and version). The information is helpful during
9012
system/firmware service events, providing additional data about the guest
9013
environments running on the machine.
9015
The information is associated with the DIAGNOSE 0x318 instruction, which sets
9016
an 8-byte value consisting of a one-byte Control Program Name Code (CPNC) and
9017
a 7-byte Control Program Version Code (CPVC). The CPNC determines what
9018
environment the control program is running in (e.g. Linux, z/VM...), and the
9019
CPVC is used for information specific to OS (e.g. Linux version, Linux
9020
distribution...)
9022
If this capability is available, then the CPNC and CPVC can be synchronized
9023
between KVM and userspace via the sync regs mechanism (KVM_SYNC_DIAG318).
9025
8.26 KVM_CAP_X86_USER_SPACE_MSR
9026
-------------------------------
9028
:Architectures: x86
9030
This capability indicates that KVM supports deflection of MSR reads and
9031
writes to user space. It can be enabled on a VM level. If enabled, MSR
9032
accesses that would usually trigger a #GP by KVM into the guest will
9033
instead get bounced to user space through the KVM_EXIT_X86_RDMSR and
9034
KVM_EXIT_X86_WRMSR exit notifications.
9036
8.27 KVM_CAP_X86_MSR_FILTER
9037
---------------------------
9039
:Architectures: x86
9041
This capability indicates that KVM supports that accesses to user defined MSRs
9042
may be rejected. With this capability exposed, KVM exports new VM ioctl
9043
KVM_X86_SET_MSR_FILTER which user space can call to specify bitmaps of MSR
9044
ranges that KVM should deny access to.
9046
In combination with KVM_CAP_X86_USER_SPACE_MSR, this allows user space to
9047
trap and emulate MSRs that are outside of the scope of KVM as well as
9048
limit the attack surface on KVM's MSR emulation code.
9050
8.30 KVM_CAP_XEN_HVM
9051
--------------------
9053
:Architectures: x86
9055
This capability indicates the features that Xen supports for hosting Xen
9056
PVHVM guests. Valid flags are::
9058
#define KVM_XEN_HVM_CONFIG_HYPERCALL_MSR (1 << 0)
9059
#define KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL (1 << 1)
9060
#define KVM_XEN_HVM_CONFIG_SHARED_INFO (1 << 2)
9061
#define KVM_XEN_HVM_CONFIG_RUNSTATE (1 << 3)
9062
#define KVM_XEN_HVM_CONFIG_EVTCHN_2LEVEL (1 << 4)
9063
#define KVM_XEN_HVM_CONFIG_EVTCHN_SEND (1 << 5)
9064
#define KVM_XEN_HVM_CONFIG_RUNSTATE_UPDATE_FLAG (1 << 6)
9065
#define KVM_XEN_HVM_CONFIG_PVCLOCK_TSC_UNSTABLE (1 << 7)
9067
The KVM_XEN_HVM_CONFIG_HYPERCALL_MSR flag indicates that the KVM_XEN_HVM_CONFIG
9068
ioctl is available, for the guest to set its hypercall page.
9070
If KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL is also set, the same flag may also be
9071
provided in the flags to KVM_XEN_HVM_CONFIG, without providing hypercall page
9072
contents, to request that KVM generate hypercall page content automatically
9073
and also enable interception of guest hypercalls with KVM_EXIT_XEN.
9075
The KVM_XEN_HVM_CONFIG_SHARED_INFO flag indicates the availability of the
9076
KVM_XEN_HVM_SET_ATTR, KVM_XEN_HVM_GET_ATTR, KVM_XEN_VCPU_SET_ATTR and
9077
KVM_XEN_VCPU_GET_ATTR ioctls, as well as the delivery of exception vectors
9078
for event channel upcalls when the evtchn_upcall_pending field of a vcpu's
9079
vcpu_info is set.
9081
The KVM_XEN_HVM_CONFIG_RUNSTATE flag indicates that the runstate-related
9082
features KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADDR/_CURRENT/_DATA/_ADJUST are
9083
supported by the KVM_XEN_VCPU_SET_ATTR/KVM_XEN_VCPU_GET_ATTR ioctls.
9085
The KVM_XEN_HVM_CONFIG_EVTCHN_2LEVEL flag indicates that IRQ routing entries
9086
of the type KVM_IRQ_ROUTING_XEN_EVTCHN are supported, with the priority
9087
field set to indicate 2 level event channel delivery.
9089
The KVM_XEN_HVM_CONFIG_EVTCHN_SEND flag indicates that KVM supports
9090
injecting event channel events directly into the guest with the
9091
KVM_XEN_HVM_EVTCHN_SEND ioctl. It also indicates support for the
9092
KVM_XEN_ATTR_TYPE_EVTCHN/XEN_VERSION HVM attributes and the
9093
KVM_XEN_VCPU_ATTR_TYPE_VCPU_ID/TIMER/UPCALL_VECTOR vCPU attributes.
9094
related to event channel delivery, timers, and the XENVER_version
9095
interception.
9097
The KVM_XEN_HVM_CONFIG_RUNSTATE_UPDATE_FLAG flag indicates that KVM supports
9098
the KVM_XEN_ATTR_TYPE_RUNSTATE_UPDATE_FLAG attribute in the KVM_XEN_SET_ATTR
9099
and KVM_XEN_GET_ATTR ioctls. This controls whether KVM will set the
9100
XEN_RUNSTATE_UPDATE flag in guest memory mapped vcpu_runstate_info during
9101
updates of the runstate information. Note that versions of KVM which support
9102
the RUNSTATE feature above, but not the RUNSTATE_UPDATE_FLAG feature, will
9103
always set the XEN_RUNSTATE_UPDATE flag when updating the guest structure,
9104
which is perhaps counterintuitive. When this flag is advertised, KVM will
9105
behave more correctly, not using the XEN_RUNSTATE_UPDATE flag until/unless
9106
specifically enabled (by the guest making the hypercall, causing the VMM
9107
to enable the KVM_XEN_ATTR_TYPE_RUNSTATE_UPDATE_FLAG attribute).
9109
The KVM_XEN_HVM_CONFIG_PVCLOCK_TSC_UNSTABLE flag indicates that KVM supports
9110
clearing the PVCLOCK_TSC_STABLE_BIT flag in Xen pvclock sources. This will be
9111
done when the KVM_CAP_XEN_HVM ioctl sets the
9112
KVM_XEN_HVM_CONFIG_PVCLOCK_TSC_UNSTABLE flag.
9114
8.31 KVM_CAP_SPAPR_MULTITCE
9115
---------------------------
9117
:Architectures: ppc
9118
:Type: vm
9120
This capability means the kernel is capable of handling hypercalls
9121
H_PUT_TCE_INDIRECT and H_STUFF_TCE without passing those into the user
9122
space. This significantly accelerates DMA operations for PPC KVM guests.
9123
User space should expect that its handlers for these hypercalls
9124
are not going to be called if user space previously registered LIOBN
9125
in KVM (via KVM_CREATE_SPAPR_TCE or similar calls).
9127
In order to enable H_PUT_TCE_INDIRECT and H_STUFF_TCE use in the guest,
9128
user space might have to advertise it for the guest. For example,
9129
IBM pSeries (sPAPR) guest starts using them if "hcall-multi-tce" is
9130
present in the "ibm,hypertas-functions" device-tree property.
9132
The hypercalls mentioned above may or may not be processed successfully
9133
in the kernel based fast path. If they can not be handled by the kernel,
9134
they will get passed on to user space. So user space still has to have
9135
an implementation for these despite the in kernel acceleration.
9137
This capability is always enabled.
9139
8.32 KVM_CAP_PTP_KVM
9140
--------------------
9142
:Architectures: arm64
9144
This capability indicates that the KVM virtual PTP service is
9145
supported in the host. A VMM can check whether the service is
9146
available to the guest on migration.
9148
8.37 KVM_CAP_S390_PROTECTED_DUMP
9149
--------------------------------
9151
:Architectures: s390
9152
:Type: vm
9154
This capability indicates that KVM and the Ultravisor support dumping
9155
PV guests. The `KVM_PV_DUMP` command is available for the
9156
`KVM_S390_PV_COMMAND` ioctl and the `KVM_PV_INFO` command provides
9157
dump related UV data. Also the vcpu ioctl `KVM_S390_PV_CPU_COMMAND` is
9158
available and supports the `KVM_PV_DUMP_CPU` subcommand.
9160
8.39 KVM_CAP_S390_CPU_TOPOLOGY
9161
------------------------------
9163
:Architectures: s390
9164
:Type: vm
9166
This capability indicates that KVM will provide the S390 CPU Topology
9167
facility which consist of the interpretation of the PTF instruction for
9168
the function code 2 along with interception and forwarding of both the
9169
PTF instruction with function codes 0 or 1 and the STSI(15,1,x)
9170
instruction to the userland hypervisor.
9172
The stfle facility 11, CPU Topology facility, should not be indicated
9173
to the guest without this capability.
9175
When this capability is present, KVM provides a new attribute group
9176
on vm fd, KVM_S390_VM_CPU_TOPOLOGY.
9177
This new attribute allows to get, set or clear the Modified Change
9178
Topology Report (MTCR) bit of the SCA through the kvm_device_attr
9179
structure.
9181
When getting the Modified Change Topology Report value, the attr->addr
9182
must point to a byte where the value will be stored or retrieved from.
9184
8.41 KVM_CAP_VM_TYPES
9185
---------------------
9187
:Architectures: x86
9188
:Type: system ioctl
9190
This capability returns a bitmap of support VM types. The 1-setting of bit @n
9191
means the VM type with value @n is supported. Possible values of @n are::
9193
#define KVM_X86_DEFAULT_VM 0
9194
#define KVM_X86_SW_PROTECTED_VM 1
9195
#define KVM_X86_SEV_VM 2
9196
#define KVM_X86_SEV_ES_VM 3
9198
Note, KVM_X86_SW_PROTECTED_VM is currently only for development and testing.
9199
Do not use KVM_X86_SW_PROTECTED_VM for "real" VMs, and especially not in
9200
production. The behavior and effective ABI for software-protected VMs is
9201
unstable.
9203
8.42 KVM_CAP_PPC_RPT_INVALIDATE
9204
-------------------------------
9206
:Architectures: ppc
9208
This capability indicates that the kernel is capable of handling
9209
H_RPT_INVALIDATE hcall.
9211
In order to enable the use of H_RPT_INVALIDATE in the guest,
9212
user space might have to advertise it for the guest. For example,
9213
IBM pSeries (sPAPR) guest starts using it if "hcall-rpt-invalidate" is
9214
present in the "ibm,hypertas-functions" device-tree property.
9216
This capability is enabled for hypervisors on platforms like POWER9
9217
that support radix MMU.
9219
8.43 KVM_CAP_PPC_AIL_MODE_3
9220
---------------------------
9222
:Architectures: ppc
9224
This capability indicates that the kernel supports the mode 3 setting for the
9225
"Address Translation Mode on Interrupt" aka "Alternate Interrupt Location"
9226
resource that is controlled with the H_SET_MODE hypercall.
9228
This capability allows a guest kernel to use a better-performance mode for
9229
handling interrupts and system calls.
9231
8.44 KVM_CAP_MEMORY_FAULT_INFO
9232
------------------------------
9234
:Architectures: x86
9236
The presence of this capability indicates that KVM_RUN will fill
9237
kvm_run.memory_fault if KVM cannot resolve a guest page fault VM-Exit, e.g. if
9238
there is a valid memslot but no backing VMA for the corresponding host virtual
9239
address.
9241
The information in kvm_run.memory_fault is valid if and only if KVM_RUN returns
9242
an error with errno=EFAULT or errno=EHWPOISON *and* kvm_run.exit_reason is set
9243
to KVM_EXIT_MEMORY_FAULT.
9245
Note: Userspaces which attempt to resolve memory faults so that they can retry
9246
KVM_RUN are encouraged to guard against repeatedly receiving the same
9247
error/annotated fault.
9249
See KVM_EXIT_MEMORY_FAULT for more information.
9251
8.45 KVM_CAP_X86_GUEST_MODE
9252
---------------------------
9254
:Architectures: x86
9256
The presence of this capability indicates that KVM_RUN will update the
9257
KVM_RUN_X86_GUEST_MODE bit in kvm_run.flags to indicate whether the
9258
vCPU was executing nested guest code when it exited.
9260
KVM exits with the register state of either the L1 or L2 guest
9261
depending on which executed at the time of an exit. Userspace must
9262
take care to differentiate between these cases.
9264
9. Known KVM API problems
9265
=========================
9267
In some cases, KVM's API has some inconsistencies or common pitfalls
9268
that userspace need to be aware of. This section details some of
9269
these issues.
9271
Most of them are architecture specific, so the section is split by
9272
architecture.
9274
9.1. x86
9275
--------
9277
``KVM_GET_SUPPORTED_CPUID`` issues
9278
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9280
In general, ``KVM_GET_SUPPORTED_CPUID`` is designed so that it is possible
9281
to take its result and pass it directly to ``KVM_SET_CPUID2``. This section
9282
documents some cases in which that requires some care.
9284
Local APIC features
9285
~~~~~~~~~~~~~~~~~~~
9287
CPU[EAX=1]:ECX[21] (X2APIC) is reported by ``KVM_GET_SUPPORTED_CPUID``,
9288
but it can only be enabled if ``KVM_CREATE_IRQCHIP`` or
9289
``KVM_ENABLE_CAP(KVM_CAP_IRQCHIP_SPLIT)`` are used to enable in-kernel emulation of
9290
the local APIC.
9292
The same is true for the ``KVM_FEATURE_PV_UNHALT`` paravirtualized feature.
9294
On older versions of Linux, CPU[EAX=1]:ECX[24] (TSC_DEADLINE) is not reported by
9295
``KVM_GET_SUPPORTED_CPUID``, but it can be enabled if ``KVM_CAP_TSC_DEADLINE_TIMER``
9296
is present and the kernel has enabled in-kernel emulation of the local APIC.
9297
On newer versions, ``KVM_GET_SUPPORTED_CPUID`` does report the bit as available.
9299
CPU topology
9300
~~~~~~~~~~~~
9302
Several CPUID values include topology information for the host CPU:
9303
0x0b and 0x1f for Intel systems, 0x8000001e for AMD systems. Different
9304
versions of KVM return different values for this information and userspace
9305
should not rely on it. Currently they return all zeroes.
9307
If userspace wishes to set up a guest topology, it should be careful that
9308
the values of these three leaves differ for each CPU. In particular,
9309
the APIC ID is found in EDX for all subleaves of 0x0b and 0x1f, and in EAX
9310
for 0x8000001e; the latter also encodes the core id and node id in bits
9311
7:0 of EBX and ECX respectively.
9313
Obsolete ioctls and capabilities
9314
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9316
KVM_CAP_DISABLE_QUIRKS does not let userspace know which quirks are actually
9317
available. Use ``KVM_CHECK_EXTENSION(KVM_CAP_DISABLE_QUIRKS2)`` instead if
9318
available.
9320
Ordering of KVM_GET_*/KVM_SET_* ioctls
9321
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9323
TBD
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
1. 일반 설명
1-59KVM API의 중심은 여러 종류의 file descriptor와 각 descriptor에 발행하는 ioctl입니다. 먼저 `open("/dev/kvm")`으로 KVM subsystem handle을 얻고 이 handle에 system ioctl을 호출합니다.
System fd에 `KVM_CREATE_VM`을 호출하면 VM fd가 생기며 VM ioctl은 이 fd를 사용합니다. VM fd에 `KVM_CREATE_VCPU` 또는 `KVM_CREATE_DEVICE`를 호출하면 virtual CPU 또는 device가 만들어지고 새 resource를 가리키는 fd가 반환됩니다.
`open("/dev/kvm")` → KVM system fd→`KVM_CREATE_VM` → VM fd→`KVM_CREATE_VCPU` → vCPU fd→`KVM_CREATE_DEVICE` → device fd→각 fd class에 맞는 ioctl 호출
Resource 생성 ioctl이 다음 계층의 fd를 반환합니다.
System ioctl은 KVM subsystem 전체에 영향을 주는 global attribute를 조회·설정하고 VM을 만듭니다. VM ioctl은 memory layout처럼 VM 전체의 attribute를 다루고 vCPU와 device를 만듭니다. VM ioctl은 VM을 만든 process, 즉 같은 address space에서 호출해야 합니다.
vCPU ioctl은 vCPU 하나의 동작을 조회·제어합니다. 문서에서 asynchronous라고 명시한 ioctl을 제외하면 vCPU를 만든 thread에서 호출하는 것이 좋습니다. 다른 thread로 전환한 뒤 첫 ioctl은 성능 저하를 겪을 수 있습니다.
Device ioctl은 device 하나의 동작을 조회·설정하며 VM을 만든 것과 같은 process에서 호출해야 합니다. 대부분의 ioctl은 fd 종류 하나에 속하지만 일부는 둘 이상의 class에 속할 수 있습니다.
Class대상Context 규칙
SystemKVM global state, VM 생성`/dev/kvm` fd
VMVM memory·attribute, vCPU·device 생성VM 생성 process
vCPU단일 virtual CPU원칙적으로 vCPU 생성 thread
Device단일 virtual deviceVM 생성 process
수신 fd와 실행 context 요구 사항입니다.
KVM API는 시간에 따라 확장됐습니다. `KVM_CAP_*` 상수는 하나 이상의 ioctl이 제공하는 기능 집합을 나타냅니다. `KVM_CHECK_EXTENSION`으로 capability 존재를 확인하며, 일부 capability는 사용할 VM 또는 vCPU에서 별도로 enable해야 합니다.
.. SPDX-License-Identifier: GPL-2.0
===================================================================
The Definitive KVM (Kernel-based Virtual Machine) API Documentation
===================================================================
1. General description
======================
The kvm API is centered around different kinds of file descriptors
and ioctls that can be issued to these file descriptors. An initial
open("/dev/kvm") obtains a handle to the kvm subsystem; this handle
can be used to issue system ioctls. A KVM_CREATE_VM ioctl on this
handle will create a VM file descriptor which can be used to issue VM
ioctls. A KVM_CREATE_VCPU or KVM_CREATE_DEVICE ioctl on a VM fd will
create a virtual cpu or device and return a file descriptor pointing to
the new resource.
In other words, the kvm API is a set of ioctls that are issued to
different kinds of file descriptor in order to control various aspects of
a virtual machine. Depending on the file descriptor that accepts them,
ioctls belong to the following classes:
- System ioctls: These query and set global attributes which affect the
whole kvm subsystem. In addition a system ioctl is used to create
virtual machines.
- VM ioctls: These query and set attributes that affect an entire virtual
machine, for example memory layout. In addition a VM ioctl is used to
create virtual cpus (vcpus) and devices.
VM ioctls must be issued from the same process (address space) that was
used to create the VM.
- vcpu ioctls: These query and set attributes that control the operation
of a single virtual cpu.
vcpu ioctls should be issued from the same thread that was used to create
the vcpu, except for asynchronous vcpu ioctl that are marked as such in
the documentation. Otherwise, the first ioctl after switching threads
could see a performance impact.
- device ioctls: These query and set attributes that control the operation
of a single device.
device ioctls must be issued from the same process (address space) that
was used to create the VM.
While most ioctls are specific to one kind of file descriptor, in some
cases the same ioctl can belong to more than one class.
The KVM API grew over time. For this reason, KVM defines many constants
of the form ``KVM_CAP_*``, each corresponding to a set of functionality
provided by one or more ioctls. Availability of these "capabilities" can
be checked with :ref:`KVM_CHECK_EXTENSION <KVM_CHECK_EXTENSION>`. Some
capabilities also need to be enabled for VMs or VCPUs where their
functionality is desired (see :ref:`cap_enable` and :ref:`cap_enable_vm`).
2. 제한과 3. Extension
60-100일반적으로 fd는 `fork()`나 Unix domain socket의 `SCM_RIGHTS`로 process 사이를 이동할 수 있지만 KVM은 이런 사용을 명시적으로 지원하지 않습니다. Host를 손상시키지는 않더라도 실제 동작은 API가 보장하지 않습니다.
VM ioctl은 VM을 만든 process만 호출할 수 있지만 VM 수명 주기는 creator process가 아니라 VM fd에 연결됩니다. VM과 관련 address space를 포함한 resource는 VM fd의 마지막 reference가 해제될 때까지 free되지 않습니다.
예를 들어 `KVM_CREATE_VM` 뒤 `fork()`하면 parent와 child가 모두 VM fd reference를 놓아야 VM이 제거됩니다. `fork()`, `dup()` 등으로 reference를 늘리면 VM 종료 후에도 process를 대신해 할당한 memory가 free되거나 accounting에서 빠지지 않을 수 있으므로 신중한 검토 없이 사용하지 않는 것이 좋습니다.
항목기준
VM ioctl 호출VM을 만든 process/address space
VM resource 해제VM fd의 마지막 reference release
지원하지 않는 이동`fork()`·`SCM_RIGHTS`를 이용한 cross-process 사용
주의할 추가 reference`fork()`, `dup()` 등
호출 권한과 resource 수명 기준은 서로 다릅니다.
Linux 2.6.22부터 KVM ABI는 안정화되어 backward-incompatible change를 허용하지 않습니다. 대신 기존 API와 호환되는 extension을 조회하고 사용하는 mechanism을 제공합니다.
Extension mechanism은 Linux version number에 기반하지 않습니다. KVM이 extension identifier와 availability query facility를 정의하며, 특정 identifier가 존재하면 application이 대응 ioctl 집합을 사용할 수 있습니다.
2. Restrictions
===============
In general file descriptors can be migrated among processes by means
of fork() and the SCM_RIGHTS facility of unix domain socket. These
kinds of tricks are explicitly not supported by kvm. While they will
not cause harm to the host, their actual behavior is not guaranteed by
the API. See "General description" for details on the ioctl usage
model that is supported by KVM.
It is important to note that although VM ioctls may only be issued from
the process that created the VM, a VM's lifecycle is associated with its
file descriptor, not its creator (process). In other words, the VM and
its resources, *including the associated address space*, are not freed
until the last reference to the VM's file descriptor has been released.
For example, if fork() is issued after ioctl(KVM_CREATE_VM), the VM will
not be freed until both the parent (original) process and its child have
put their references to the VM's file descriptor.
Because a VM's resources are not freed until the last reference to its
file descriptor is released, creating additional references to a VM
via fork(), dup(), etc... without careful consideration is strongly
discouraged and may have unwanted side effects, e.g. memory allocated
by and on behalf of the VM's process may not be freed/unaccounted when
the VM is shut down.
3. Extensions
=============
As of Linux 2.6.22, the KVM ABI has been stabilized: no backward
incompatible change are allowed. However, there is an extension
facility that allows backward-compatible extensions to the API to be
queried and used.
The extension mechanism is not based on the Linux version number.
Instead, kvm defines extension identifiers and a facility to query
whether a particular extension identifier is available. If it is, a
set of ioctls is available for application use.
4. API 항목의 공통 필드
101-129API 설명 절은 KVM guest를 제어하는 ioctl마다 공통 metadata를 제공합니다.
`Capability`는 ioctl을 제공하는 KVM extension입니다. `basic`이면 API version 12를 지원하는 모든 kernel에 존재하고, 그렇지 않으면 `KVM_CHECK_EXTENSION`으로 확인할 `KVM_CAP_xyz` 상수입니다.
`Architectures`는 ioctl을 제공하는 instruction set architecture를 나타내며 x86은 i386과 x86_64를 모두 포함합니다. `Type`은 system, VM, vCPU 중 수신 fd class입니다.
`Parameters`는 ioctl이 받는 argument를, `Returns`는 return value를 설명합니다. `EBADF`, `ENOMEM`, `EINVAL` 같은 일반 error는 반복하지 않고 해당 ioctl에서 특별한 의미를 갖는 error만 상세히 적습니다.
Field의미
CapabilityBasic 또는 `KVM_CAP_*` 요구
Architectures지원 ISA
TypeSystem·VM·vCPU fd class
Parameters입력·출력 argument
Returns성공값과 특별한 error
각 API entry를 읽을 때 확인할 계약입니다.
4. API description
==================
This section describes ioctls that can be used to control kvm guests.
For each ioctl, the following information is provided along with a
description:
Capability:
which KVM extension provides this ioctl. Can be 'basic',
which means that is will be provided by any kernel that supports
API version 12 (see :ref:`KVM_GET_API_VERSION <KVM_GET_API_VERSION>`),
or a KVM_CAP_xyz constant that can be checked with
:ref:`KVM_CHECK_EXTENSION <KVM_CHECK_EXTENSION>`.
Architectures:
which instruction set architectures provide this ioctl.
x86 includes both i386 and x86_64.
Type:
system, vm, or vcpu.
Parameters:
what parameters are accepted by the ioctl.
Returns:
the return value. General error numbers (EBADF, ENOMEM, EINVAL)
are not detailed, but errors with specific meanings are.
4.1 KVM_GET_API_VERSION
130-148`KVM_GET_API_VERSION`은 모든 architecture의 system ioctl이며 argument 없이 stable KVM API version인 `KVM_API_VERSION`, 즉 12를 반환합니다.
이 version은 바뀔 것으로 예상하지 않습니다. Linux 2.6.20과 2.6.21은 더 이른 version을 보고하지만 문서화되지 않았고 지원 대상도 아닙니다.
Application은 return value가 12가 아니면 실행을 거부해야 합니다. 12 확인이 성공하면 `basic`으로 표시된 모든 ioctl을 사용할 수 있습니다.
결과처리
12Stable API, 모든 basic ioctl 사용 가능
12 이외지원하지 않으므로 application 실행 거부
Userspace가 최초에 검사해야 하는 고정 계약입니다.
.. _KVM_GET_API_VERSION:
4.1 KVM_GET_API_VERSION
-----------------------
:Capability: basic
:Architectures: all
:Type: system ioctl
:Parameters: none
:Returns: the constant KVM_API_VERSION (=12)
This identifies the API version as the stable kvm API. It is not
expected that this number will change. However, Linux 2.6.20 and
2.6.21 report earlier versions; these are not documented and not
supported. Applications should refuse to run if KVM_GET_API_VERSION
returns a value other than 12. If this check passes, all ioctls
described as 'basic' will be available.
4.2 KVM_CREATE_VM
149-217`KVM_CREATE_VM`은 모든 architecture의 basic system ioctl입니다. `KVM_VM_*` machine type identifier를 받고 새 VM을 제어할 VM fd를 반환합니다. 새 VM에는 아직 vCPU도 memory도 없으며 일반적으로 machine type 0을 사용합니다.
x86에서 지원하는 VM type은 `KVM_CAP_VM_TYPES`로 조회할 수 있습니다. S390에서 userspace-controlled VM을 만들려면 `KVM_CAP_S390_UCONTROL`을 확인하고 `CAP_SYS_ADMIN` 권한으로 `KVM_VM_S390_UCONTROL` flag를 사용합니다.
MIPS에서 default trap-and-emulate 구현 대신 VZ ASE hardware-assisted virtualization을 사용하려면 `KVM_CAP_MIPS_VZ`를 확인하고 `KVM_VM_MIPS_VZ` flag를 지정합니다.
Arm64 VM의 physical address, 즉 IPA size limit은 기본 40 bit입니다. Host가 `KVM_CAP_ARM_VM_IPA_SIZE` extension을 지원하면 machine type의 `KVM_VM_TYPE_ARM_IPA_SIZE(IPA_Bits)`로 limit을 설정하며 `IPA_Bits`는 VM이 사용할 physical address의 최대 폭입니다. 값은 machine type identifier의 bit 7:0에 encode됩니다.
예를 들어 48-bit guest physical address는 `ioctl(dev_fd, KVM_CREATE_VM, KVM_VM_TYPE_ARM_IPA_SIZE(48))`로 요청합니다.
값의미
0Backward compatibility를 위한 default 40 bit
N32 ≤ N ≤ Host_IPA_Limit인 양의 정수
요청값과 의미입니다.
`Host_IPA_Limit`은 CPU capability와 kernel configuration에 따른 host 최대값이며 runtime에 `KVM_CHECK_EXTENSION(KVM_CAP_ARM_VM_IPA_SIZE)`으로 얻습니다. Explicit 또는 implicit IPA size가 host에서 지원되지 않으면 VM 생성이 실패합니다.
IPA size 설정은 guest CPU가 `ID_AA64MMFR0_EL1[PARange]`로 노출하는 capability를 바꾸지 않습니다. Guest physical address를 host physical address로 바꾸는 stage-2 translation의 address size에만 영향을 줍니다.
ArchitectureCapability·flag목적
x86`KVM_CAP_VM_TYPES`지원 VM type 조회
S390`KVM_CAP_S390_UCONTROL`, `KVM_VM_S390_UCONTROL`User-controlled VM
MIPS`KVM_CAP_MIPS_VZ`, `KVM_VM_MIPS_VZ`VZ hardware virtualization
arm64`KVM_CAP_ARM_VM_IPA_SIZE`Stage-2 IPA width 설정
기본 VM 생성 외 architecture 전용 선택입니다.
4.2 KVM_CREATE_VM
-----------------
:Capability: basic
:Architectures: all
:Type: system ioctl
:Parameters: machine type identifier (KVM_VM_*)
:Returns: a VM fd that can be used to control the new virtual machine.
The new VM has no virtual cpus and no memory.
You probably want to use 0 as machine type.
X86:
^^^^
Supported X86 VM types can be queried via KVM_CAP_VM_TYPES.
S390:
^^^^^
In order to create user controlled virtual machines on S390, check
KVM_CAP_S390_UCONTROL and use the flag KVM_VM_S390_UCONTROL as
privileged user (CAP_SYS_ADMIN).
MIPS:
^^^^^
To use hardware assisted virtualization on MIPS (VZ ASE) rather than
the default trap & emulate implementation (which changes the virtual
memory layout to fit in user mode), check KVM_CAP_MIPS_VZ and use the
flag KVM_VM_MIPS_VZ.
ARM64:
^^^^^^
On arm64, the physical address size for a VM (IPA Size limit) is limited
to 40bits by default. The limit can be configured if the host supports the
extension KVM_CAP_ARM_VM_IPA_SIZE. When supported, use
KVM_VM_TYPE_ARM_IPA_SIZE(IPA_Bits) to set the size in the machine type
identifier, where IPA_Bits is the maximum width of any physical
address used by the VM. The IPA_Bits is encoded in bits[7-0] of the
machine type identifier.
e.g, to configure a guest to use 48bit physical address size::
vm_fd = ioctl(dev_fd, KVM_CREATE_VM, KVM_VM_TYPE_ARM_IPA_SIZE(48));
The requested size (IPA_Bits) must be:
== =========================================================
0 Implies default size, 40bits (for backward compatibility)
N Implies N bits, where N is a positive integer such that,
32 <= N <= Host_IPA_Limit
== =========================================================
Host_IPA_Limit is the maximum possible value for IPA_Bits on the host and
is dependent on the CPU capability and the kernel configuration. The limit can
be retrieved using KVM_CAP_ARM_VM_IPA_SIZE of the KVM_CHECK_EXTENSION
ioctl() at run-time.
Creation of the VM will fail if the requested IPA size (whether it is
implicit or explicit) is unsupported on the host.
Please note that configuring the IPA size does not affect the capability
exposed by the guest CPUs in ID_AA64MMFR0_EL1[PARange]. It only affects
size of the address translated by the stage2 level (guest physical to
host physical address translations).
4.3 KVM_GET_MSR_INDEX_LIST 계열
218-259`KVM_GET_MSR_INDEX_LIST`와 `KVM_GET_MSR_FEATURE_INDEX_LIST`는 x86 system ioctl이며 `struct kvm_msr_list`를 입출력으로 사용합니다. Feature index list에는 `KVM_CAP_GET_MSR_FEATURES`가 필요합니다.
성공하면 0, 실패하면 -1입니다. MSR index list를 userspace에서 읽거나 쓸 수 없으면 `EFAULT`, 사용자가 제공한 array보다 실제 list가 크면 `E2BIG`입니다.
`struct kvm_msr_list`의 `nmsrs`는 `indices` array의 entry 수입니다. Userspace가 먼저 array capacity를 `nmsrs`에 넣고 호출하면 KVM이 실제 MSR 수로 값을 고친 뒤 `indices`에 번호를 채웁니다.
`KVM_GET_MSR_INDEX_LIST`는 지원하는 guest MSR을 반환합니다. 목록은 KVM version과 host processor에 따라 달라지지만 같은 조건에서는 변하지 않습니다.
KVM이 `KVM_CAP_MCE`를 지원해도 MCE bank MSR은 목록에 넣지 않습니다. `KVM_X86_SETUP_MCE` 설정에 따라 vCPU마다 bank 수가 다를 수 있기 때문입니다.
`KVM_GET_MSR_FEATURE_INDEX_LIST`는 `KVM_GET_MSRS` system ioctl에 전달할 수 있는 MSR 목록을 반환합니다. Userspace는 이를 이용해 VMX capability처럼 MSR로 노출되는 host capability와 processor feature를 probe합니다.
ioctl반환 목록
`KVM_GET_MSR_INDEX_LIST`지원하는 guest MSR
`KVM_GET_MSR_FEATURE_INDEX_LIST`System `KVM_GET_MSRS`로 읽을 host feature MSR
Guest state용 MSR과 host feature probe용 MSR을 구분합니다.
4.3 KVM_GET_MSR_INDEX_LIST, KVM_GET_MSR_FEATURE_INDEX_LIST
----------------------------------------------------------
:Capability: basic, KVM_CAP_GET_MSR_FEATURES for KVM_GET_MSR_FEATURE_INDEX_LIST
:Architectures: x86
:Type: system ioctl
:Parameters: struct kvm_msr_list (in/out)
:Returns: 0 on success; -1 on error
Errors:
====== ============================================================
EFAULT the msr index list cannot be read from or written to
E2BIG the msr index list is too big to fit in the array specified by
the user.
====== ============================================================
::
struct kvm_msr_list {
__u32 nmsrs; /* number of msrs in entries */
__u32 indices[0];
};
The user fills in the size of the indices array in nmsrs, and in return
kvm adjusts nmsrs to reflect the actual number of msrs and fills in the
indices array with their numbers.
KVM_GET_MSR_INDEX_LIST returns the guest msrs that are supported. The list
varies by kvm version and host processor, but does not change otherwise.
Note: if kvm indicates supports MCE (KVM_CAP_MCE), then the MCE bank MSRs are
not returned in the MSR list, as different vcpus can have a different number
of banks, as set via the KVM_X86_SETUP_MCE ioctl.
KVM_GET_MSR_FEATURE_INDEX_LIST returns the list of MSRs that can be passed
to the KVM_GET_MSRS system ioctl. This lets userspace probe host capabilities
and processor features that are exposed via MSRs (e.g., VMX capabilities).
This list also varies by kvm version and host processor, but does not change
otherwise.
4.4 KVM_CHECK_EXTENSION
260-280`KVM_CHECK_EXTENSION`은 모든 architecture에서 core KVM API extension을 조회합니다. System ioctl로 사용할 수 있고 `KVM_CAP_CHECK_EXTENSION_VM`이 있으면 VM ioctl로도 사용할 수 있습니다.
Userspace가 `KVM_CAP_*` integer identifier를 전달하면 availability를 설명하는 integer가 돌아옵니다. 일반적으로 0은 미지원, 1은 지원이지만 일부 extension은 양의 return value에 추가 정보를 담습니다.
VM initialization에 따라 서로 다른 VM이 다른 capability를 가질 수 있습니다. 따라서 가능하면 VM fd에서 `KVM_CAP_CHECK_EXTENSION_VM`을 사용해 capability를 조회하는 것이 권장됩니다.
Return의미
0Unsupported
1Supported
> 1Supported이며 capability-specific 추가 정보 포함 가능
Boolean 외의 positive value도 허용됩니다.
.. _KVM_CHECK_EXTENSION:
4.4 KVM_CHECK_EXTENSION
-----------------------
:Capability: basic, KVM_CAP_CHECK_EXTENSION_VM for vm ioctl
:Architectures: all
:Type: system ioctl, vm ioctl
:Parameters: extension identifier (KVM_CAP_*)
:Returns: 0 if unsupported; 1 (or some other positive integer) if supported
The API allows the application to query about extensions to the core
kvm API. Userspace passes an extension identifier (an integer) and
receives an integer that describes the extension availability.
Generally 0 means no and 1 means yes, but some extensions may report
additional information in the integer return value.
Based on their initialization different VMs may have different capabilities.
It is thus encouraged to use the vm ioctl to query for capabilities (available
with KVM_CAP_CHECK_EXTENSION_VM on the vm fd)
4.5 KVM_GET_VCPU_MMAP_SIZE
281-306`KVM_GET_VCPU_MMAP_SIZE`는 모든 architecture의 basic system ioctl이며 argument 없이 vCPU mmap area size를 byte 단위로 반환합니다.
`KVM_RUN`은 shared memory region으로 userspace와 통신합니다. 이 ioctl이 그 region의 크기를 알려 주며 자세한 layout은 `KVM_RUN` 설명을 따릅니다.
vCPU fd에는 KVM_RUN communication region 외에도 mapping할 수 있는 영역이 있습니다. `KVM_CAP_COALESCED_MMIO`가 있으면 `KVM_COALESCED_MMIO_PAGE_OFFSET * PAGE_SIZE` 위치의 page를 mapping할 수 있고 historical reason으로 이 page 크기도 return value에 포함됩니다.
`KVM_CAP_DIRTY_LOG_RING`이 있으면 `KVM_DIRTY_LOG_PAGE_OFFSET * PAGE_SIZE` 위치에서 여러 page를 mapping할 수 있습니다. 상세 동작은 해당 capability 문서를 참조합니다.
영역조건·offset
KVM_RUN communicationOffset 0, 반환 크기의 기본 영역
Coalesced MMIO`KVM_CAP_COALESCED_MMIO`, `KVM_COALESCED_MMIO_PAGE_OFFSET`
Dirty log ring`KVM_CAP_DIRTY_LOG_RING`, `KVM_DIRTY_LOG_PAGE_OFFSET`
Capability에 따라 기본 run region 뒤에 추가 mapping이 있습니다.
4.5 KVM_GET_VCPU_MMAP_SIZE
--------------------------
:Capability: basic
:Architectures: all
:Type: system ioctl
:Parameters: none
:Returns: size of vcpu mmap area, in bytes
The KVM_RUN ioctl (cf.) communicates with userspace via a shared
memory region. This ioctl returns the size of that region. See the
KVM_RUN documentation for details.
Besides the size of the KVM_RUN communication region, other areas of
the VCPU file descriptor can be mmap-ed, including:
- if KVM_CAP_COALESCED_MMIO is available, a page at
KVM_COALESCED_MMIO_PAGE_OFFSET * PAGE_SIZE; for historical reasons,
this page is included in the result of KVM_GET_VCPU_MMAP_SIZE.
KVM_CAP_COALESCED_MMIO is not documented yet.
- if KVM_CAP_DIRTY_LOG_RING is available, a number of pages at
KVM_DIRTY_LOG_PAGE_OFFSET * PAGE_SIZE. For more information on
KVM_CAP_DIRTY_LOG_RING, see :ref:`KVM_CAP_DIRTY_LOG_RING`.
4.7 KVM_CREATE_VCPU
307-353`KVM_CREATE_VCPU`는 모든 architecture의 basic VM ioctl입니다. vCPU id, x86에서는 APIC id를 받아 성공 시 vCPU fd를 반환하며 한 VM에 `max_vcpus`보다 많이 만들 수 없습니다. ID 범위는 `[0, max_vcpu_id)`입니다.
권장 `max_vcpus`는 runtime에 `KVM_CAP_NR_VCPUS`, 절대 최대값은 `KVM_CAP_MAX_VCPUS`, 최대 ID 범위는 `KVM_CAP_MAX_VCPU_ID`로 조회합니다.
`KVM_CAP_NR_VCPUS`가 없으면 최대 4 CPU로 가정합니다. `KVM_CAP_MAX_VCPUS`가 없으면 `KVM_CAP_NR_VCPUS` 값을, `KVM_CAP_MAX_VCPU_ID`가 없으면 `KVM_CAP_MAX_VCPUS` 값을 사용합니다.
Query없을 때 값
`KVM_CAP_NR_VCPUS`4
`KVM_CAP_MAX_VCPUS``KVM_CAP_NR_VCPUS` 결과
`KVM_CAP_MAX_VCPU_ID``KVM_CAP_MAX_VCPUS` 결과
Capability가 없는 오래된 KVM을 위한 규칙입니다.
PowerPC book3s_hv mode에서는 hardware가 CPU core의 모든 hardware thread를 같은 partition에 두도록 요구하므로 vCPU를 하나 이상의 virtual CPU core 안 virtual thread에 mapping합니다.
`KVM_CAP_PPC_SMT`는 virtual core(vcore)당 vCPU 수를 나타냅니다. vcore id는 vCPU id를 이 수로 나누어 구하며 같은 vcore의 vCPU는 항상 같은 physical core에 놓입니다. Userspace는 vCPU id allocation으로 guest SMT mode를 제어할 수 있고 single-thread guest라면 모든 ID를 vcore당 vCPU 수의 배수로 정합니다.
S390 userspace-controlled VM의 vCPU fd는 page offset `KVM_S390_SIE_PAGE_OFFSET`에서 mmap해 virtual CPU hardware control block을 mapping할 수 있습니다.
4.7 KVM_CREATE_VCPU
-------------------
:Capability: basic
:Architectures: all
:Type: vm ioctl
:Parameters: vcpu id (apic id on x86)
:Returns: vcpu fd on success, -1 on error
This API adds a vcpu to a virtual machine. No more than max_vcpus may be added.
The vcpu id is an integer in the range [0, max_vcpu_id).
The recommended max_vcpus value can be retrieved using the KVM_CAP_NR_VCPUS of
the KVM_CHECK_EXTENSION ioctl() at run-time.
The maximum possible value for max_vcpus can be retrieved using the
KVM_CAP_MAX_VCPUS of the KVM_CHECK_EXTENSION ioctl() at run-time.
If the KVM_CAP_NR_VCPUS does not exist, you should assume that max_vcpus is 4
cpus max.
If the KVM_CAP_MAX_VCPUS does not exist, you should assume that max_vcpus is
same as the value returned from KVM_CAP_NR_VCPUS.
The maximum possible value for max_vcpu_id can be retrieved using the
KVM_CAP_MAX_VCPU_ID of the KVM_CHECK_EXTENSION ioctl() at run-time.
If the KVM_CAP_MAX_VCPU_ID does not exist, you should assume that max_vcpu_id
is the same as the value returned from KVM_CAP_MAX_VCPUS.
On powerpc using book3s_hv mode, the vcpus are mapped onto virtual
threads in one or more virtual CPU cores. (This is because the
hardware requires all the hardware threads in a CPU core to be in the
same partition.) The KVM_CAP_PPC_SMT capability indicates the number
of vcpus per virtual core (vcore). The vcore id is obtained by
dividing the vcpu id by the number of vcpus per vcore. The vcpus in a
given vcore will always be in the same physical core as each other
(though that might be a different physical core from time to time).
Userspace can control the threading (SMT) mode of the guest by its
allocation of vcpu ids. For example, if userspace wants
single-threaded guest vcpus, it should make all vcpu ids be a multiple
of the number of vcpus per vcore.
For virtual cpus that have been created with S390 user controlled virtual
machines, the resulting vcpu fd can be memory mapped at page offset
KVM_S390_SIE_PAGE_OFFSET in order to obtain a memory map of the virtual
cpu's hardware control block.
4.8 KVM_GET_DIRTY_LOG
354-391`KVM_GET_DIRTY_LOG`는 모든 architecture의 basic VM ioctl입니다. `struct kvm_dirty_log`를 입출력으로 받아 memory slot에서 마지막 호출 뒤 dirty가 된 page bitmap을 반환합니다.
`slot`은 memory slot 번호이고 `dirty_bitmap`은 page마다 한 bit를 담는 userspace buffer입니다. Bit 0은 slot의 첫 page입니다. Padding 문제를 피하려면 userspace가 structure 전체를 0으로 clear해야 합니다.
`KVM_CAP_MULTI_ADDRESS_SPACE`가 있으면 `slot` field의 bit 16~31이 dirty bitmap을 조회할 address space를 지정합니다. Slot encoding은 `KVM_SET_USER_MEMORY_REGION` 설명을 따릅니다.
기본적으로 dirty bitmap bit는 ioctl이 return하기 전에 clear됩니다. `KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2`가 enable되어 있으면 자동 clear하지 않습니다.
Xen `shared_info` page를 구성한 경우에는 언제나 dirty라고 가정해야 합니다. KVM은 이 page를 명시적으로 mark하지 않습니다.
항목규칙
Bit mappingBit 0 = memory slot 첫 page
Structure 초기화Padding 포함 전체 zero
Multi address space`slot[31:16]`에 address space
Return 전 bit기본 clear, MANUAL_DIRTY_LOG_PROTECT2면 유지
Xen shared_info항상 dirty로 간주, KVM은 mark하지 않음
Memory migration·snapshot에서 놓치기 쉬운 동작입니다.
4.8 KVM_GET_DIRTY_LOG
---------------------
:Capability: basic
:Architectures: all
:Type: vm ioctl
:Parameters: struct kvm_dirty_log (in/out)
:Returns: 0 on success, -1 on error
::
/* for KVM_GET_DIRTY_LOG */
struct kvm_dirty_log {
__u32 slot;
__u32 padding;
union {
void __user *dirty_bitmap; /* one bit per page */
__u64 padding;
};
};
Given a memory slot, return a bitmap containing any pages dirtied
since the last call to this ioctl. Bit 0 is the first page in the
memory slot. Ensure the entire structure is cleared to avoid padding
issues.
If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 of slot field specifies
the address space for which you want to return the dirty bitmap. See
KVM_SET_USER_MEMORY_REGION for details on the usage of slot field.
The bits in the dirty bitmap are cleared before the ioctl returns, unless
KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 is enabled. For more information,
see the description of the capability.
Note that the Xen shared_info page, if configured, shall always be assumed
to be dirty. KVM will not explicitly mark it such.
4.10 KVM_RUN 기본 계약
392-418`KVM_RUN`은 모든 architecture의 basic vCPU ioctl이며 explicit argument 없이 guest virtual CPU를 실행합니다. 성공 시 0, 실패 시 -1입니다.
Unmasked signal이 pending이면 `EINTR`입니다. vCPU가 초기화되지 않았거나 arm64 guest가 device memory에서 instruction을 실행하면 `ENOEXEC`입니다.
Arm64에서 memslot 밖 data abort에 syndrome 정보가 없고 `KVM_CAP_ARM_NISV_TO_USER`가 enable되지 않았으면 `ENOSYS`, SVE feature를 설정했지만 finalize하지 않았으면 `EPERM`입니다.
Explicit parameter는 없지만 vCPU fd의 offset 0을 `KVM_GET_VCPU_MMAP_SIZE` 크기로 mmap해 implicit parameter block을 얻습니다. 이 block은 뒤에서 설명하는 `struct kvm_run` 형식입니다.
errno의미
EINTRUnmasked signal pending
ENOEXECvCPU 미초기화 또는 arm64 device-memory execute
ENOSYSarm64 NISV 정보 없는 memslot 밖 abort
EPERMarm64 SVE 설정 후 미완료
일반 errno 외 문서가 특별히 정의하는 원인입니다.
4.10 KVM_RUN
------------
:Capability: basic
:Architectures: all
:Type: vcpu ioctl
:Parameters: none
:Returns: 0 on success, -1 on error
Errors:
======= ==============================================================
EINTR an unmasked signal is pending
ENOEXEC the vcpu hasn't been initialized or the guest tried to execute
instructions from device memory (arm64)
ENOSYS data abort outside memslots with no syndrome info and
KVM_CAP_ARM_NISV_TO_USER not enabled (arm64)
EPERM SVE feature set but not finalized (arm64)
======= ==============================================================
This ioctl is used to run a guest virtual cpu. While there are no
explicit parameters, there is an implicit parameter block that can be
obtained by mmap()ing the vcpu fd at offset 0, with the size given by
KVM_GET_VCPU_MMAP_SIZE. The parameter block is formatted as a 'struct
kvm_run' (see below).
4.11 KVM_GET_REGS
419-458`KVM_GET_REGS`는 arm64를 제외한 모든 architecture의 basic vCPU ioctl입니다. `struct kvm_regs`에 vCPU general-purpose register를 읽어 성공 시 0을 반환합니다.
x86 structure에는 `rax`부터 `rdx`, `rsi`, `rdi`, stack·base pointer, `r8`~`r15`, instruction pointer `rip`, `rflags`가 64-bit field로 들어갑니다.
MIPS structure에는 32개 GPR, `hi`, `lo`, `pc`가 있고 LoongArch structure에는 32개 `unsigned long` GPR과 `pc`가 있습니다. 같은 structure는 `KVM_SET_REGS` 입력에도 사용됩니다.
Architecture주요 field
x86rax-rdx, rsi/rdi/rsp/rbp, r8-r15, rip, rflags
MIPSgpr[32], hi, lo, pc
LoongArchgpr[32], pc
원문에 제시된 general register 집합입니다.
4.11 KVM_GET_REGS
-----------------
:Capability: basic
:Architectures: all except arm64
:Type: vcpu ioctl
:Parameters: struct kvm_regs (out)
:Returns: 0 on success, -1 on error
Reads the general purpose registers from the vcpu.
::
/* x86 */
struct kvm_regs {
/* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
__u64 rax, rbx, rcx, rdx;
__u64 rsi, rdi, rsp, rbp;
__u64 r8, r9, r10, r11;
__u64 r12, r13, r14, r15;
__u64 rip, rflags;
};
/* mips */
struct kvm_regs {
/* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
__u64 gpr[32];
__u64 hi;
__u64 lo;
__u64 pc;
};
/* LoongArch */
struct kvm_regs {
/* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
unsigned long gpr[32];
unsigned long pc;
};
4.12 KVM_SET_REGS
459-472`KVM_SET_REGS`는 arm64를 제외한 모든 architecture의 basic vCPU ioctl입니다. 입력 `struct kvm_regs` 값을 vCPU general-purpose register에 씁니다.
성공 시 0, 실패 시 -1이며 data structure는 바로 앞의 `KVM_GET_REGS` 정의를 사용합니다. Register snapshot을 복원할 때 architecture에 맞는 layout을 제공해야 합니다.
4.12 KVM_SET_REGS
-----------------
:Capability: basic
:Architectures: all except arm64
:Type: vcpu ioctl
:Parameters: struct kvm_regs (in)
:Returns: 0 on success, -1 on error
Writes the general purpose registers into the vcpu.
See KVM_GET_REGS for the data structure.
4.13 KVM_GET_SREGS
473-503`KVM_GET_SREGS`는 x86과 PowerPC의 basic vCPU ioctl이며 `struct kvm_sregs`로 special register를 읽습니다.
x86 structure에는 segment register `cs`, `ds`, `es`, `fs`, `gs`, `ss`, task·LDT segment, `gdt`, `idt`, control register `cr0`, `cr2`, `cr3`, `cr4`, `cr8`, `efer`, `apic_base`, pending external interrupt bitmap이 포함됩니다. PowerPC layout은 `arch/powerpc/include/uapi/asm/kvm.h`를 참조합니다.
`interrupt_bitmap`은 pending external interrupt bitmap이며 최대 한 bit만 set될 수 있습니다. 이 interrupt는 APIC에서는 acknowledge됐지만 아직 CPU core에 inject되지 않은 상태입니다.
그룹Field
Segmentscs, ds, es, fs, gs, ss, tr, ldt
Descriptor tablesgdt, idt
Controlcr0, cr2, cr3, cr4, cr8, efer
APICapic_base, interrupt_bitmap
Special register state의 주요 그룹입니다.
4.13 KVM_GET_SREGS
------------------
:Capability: basic
:Architectures: x86, ppc
:Type: vcpu ioctl
:Parameters: struct kvm_sregs (out)
:Returns: 0 on success, -1 on error
Reads special registers from the vcpu.
::
/* x86 */
struct kvm_sregs {
struct kvm_segment cs, ds, es, fs, gs, ss;
struct kvm_segment tr, ldt;
struct kvm_dtable gdt, idt;
__u64 cr0, cr2, cr3, cr4, cr8;
__u64 efer;
__u64 apic_base;
__u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64];
};
/* ppc -- see arch/powerpc/include/uapi/asm/kvm.h */
interrupt_bitmap is a bitmap of pending external interrupts. At most
one bit may be set. This interrupt has been acknowledged by the APIC
but not yet injected into the cpu core.
4.14 KVM_SET_SREGS
504-515`KVM_SET_SREGS`는 x86과 PowerPC의 basic vCPU ioctl이며 입력 `struct kvm_sregs`를 vCPU special register에 씁니다.
성공 시 0, 실패 시 -1입니다. Structure layout과 `interrupt_bitmap` 의미는 `KVM_GET_SREGS` 설명을 그대로 따릅니다.
4.14 KVM_SET_SREGS
------------------
:Capability: basic
:Architectures: x86, ppc
:Type: vcpu ioctl
:Parameters: struct kvm_sregs (in)
:Returns: 0 on success, -1 on error
Writes special registers into the vcpu. See KVM_GET_SREGS for the
data structures.
4.15 KVM_TRANSLATE
516-543`KVM_TRANSLATE`는 x86 basic vCPU ioctl입니다. 입력 `linear_address`를 현재 vCPU의 address translation mode에 따라 변환하고 성공 시 0, 실패 시 -1을 반환합니다.
출력에는 변환된 `physical_address`와 함께 결과가 유효한지 나타내는 `valid`, 쓰기 가능한 mapping인지 나타내는 `writeable`, user mode에서 접근 가능한지 나타내는 `usermode`가 들어갑니다. 나머지 `pad[5]`는 구조 정렬을 위한 자리입니다.
방향Field의미
입력`linear_address`변환할 guest linear address
출력`physical_address`변환된 guest physical address
출력`valid`변환 결과 유효 여부
출력`writeable`, `usermode`쓰기 및 user-mode 접근 속성
현재 vCPU address translation 상태를 기준으로 한 단일 주소 변환 결과입니다.
4.15 KVM_TRANSLATE
------------------
:Capability: basic
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_translation (in/out)
:Returns: 0 on success, -1 on error
Translates a virtual address according to the vcpu's current address
translation mode.
::
struct kvm_translation {
/* in */
__u64 linear_address;
/* out */
__u64 physical_address;
__u8 valid;
__u8 writeable;
__u8 usermode;
__u8 pad[5];
};
4.16 KVM_INTERRUPT
544-642`KVM_INTERRUPT`는 x86, PowerPC, MIPS, RISC-V, LoongArch의 basic vCPU ioctl입니다. `struct kvm_interrupt`의 `irq` 값으로 hardware interrupt vector 또는 architecture별 external interrupt 동작을 queue합니다. 성공 시 0, 실패 시 음수를 반환합니다.
x86에서 `irq`는 interrupt pin이나 line이 아니라 interrupt vector입니다. In-kernel PIC를 사용하지 않을 때 유용합니다.
값의미
0성공
`-EEXIST`이미 interrupt가 queue됨
`-EINVAL`잘못된 irq 번호
`-ENXIO`PIC가 kernel 안에 있음
`-EFAULT`잘못된 pointer
x86에서 문서가 정의한 결과입니다.
PowerPC에서는 `KVM_INTERRUPT_SET`이 guest가 받을 준비가 되었을 때 edge-type external interrupt를 한 번 inject하고 종료합니다. `KVM_INTERRUPT_UNSET`은 pending interrupt를 취소하며 `KVM_CAP_PPC_UNSET_IRQ`가 필요합니다.
PowerPC의 `KVM_INTERRUPT_SET_LEVEL`은 level-type external interrupt를 guest context에 넣고 명시적인 `KVM_INTERRUPT_UNSET` 호출 전까지 pending 상태로 유지합니다. 이 동작에는 `KVM_CAP_PPC_IRQ_LEVEL`이 필요합니다.
PowerPC에서 위 세 값 이외의 `irq`는 유효하지 않으며 예상하지 못한 동작을 일으킵니다. 이 ioctl은 asynchronous vCPU ioctl이므로 어느 thread에서든 호출할 수 있습니다.
MIPS와 LoongArch에서는 external interrupt를 queue하며 음수 interrupt 번호를 주면 dequeue합니다. 두 architecture 모두 어느 thread에서든 호출할 수 있는 asynchronous vCPU ioctl입니다.
RISC-V의 `KVM_INTERRUPT_SET`은 vCPU가 받을 준비가 되는 즉시 external interrupt를 전달하도록 설정하고, `KVM_INTERRUPT_UNSET`은 pending external interrupt를 clear합니다. 이 역시 asynchronous ioctl입니다.
Architecture값과 동작
x86Hardware interrupt vector
PowerPCSET, UNSET, SET_LEVEL
MIPS번호 queue, 음수면 dequeue
RISC-VSET 또는 UNSET
LoongArch번호 queue, 음수면 dequeue
동일한 `irq` field가 architecture에 따라 다른 계약을 가집니다.
4.16 KVM_INTERRUPT
------------------
:Capability: basic
:Architectures: x86, ppc, mips, riscv, loongarch
:Type: vcpu ioctl
:Parameters: struct kvm_interrupt (in)
:Returns: 0 on success, negative on failure.
Queues a hardware interrupt vector to be injected.
::
/* for KVM_INTERRUPT */
struct kvm_interrupt {
/* in */
__u32 irq;
};
X86:
^^^^
:Returns:
========= ===================================
0 on success,
-EEXIST if an interrupt is already enqueued
-EINVAL the irq number is invalid
-ENXIO if the PIC is in the kernel
-EFAULT if the pointer is invalid
========= ===================================
Note 'irq' is an interrupt vector, not an interrupt pin or line. This
ioctl is useful if the in-kernel PIC is not used.
PPC:
^^^^
Queues an external interrupt to be injected. This ioctl is overloaded
with 3 different irq values:
a) KVM_INTERRUPT_SET
This injects an edge type external interrupt into the guest once it's ready
to receive interrupts. When injected, the interrupt is done.
b) KVM_INTERRUPT_UNSET
This unsets any pending interrupt.
Only available with KVM_CAP_PPC_UNSET_IRQ.
c) KVM_INTERRUPT_SET_LEVEL
This injects a level type external interrupt into the guest context. The
interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET
is triggered.
Only available with KVM_CAP_PPC_IRQ_LEVEL.
Note that any value for 'irq' other than the ones stated above is invalid
and incurs unexpected behavior.
This is an asynchronous vcpu ioctl and can be invoked from any thread.
MIPS:
^^^^^
Queues an external interrupt to be injected into the virtual CPU. A negative
interrupt number dequeues the interrupt.
This is an asynchronous vcpu ioctl and can be invoked from any thread.
RISC-V:
^^^^^^^
Queues an external interrupt to be injected into the virtual CPU. This ioctl
is overloaded with 2 different irq values:
a) KVM_INTERRUPT_SET
This sets external interrupt for a virtual CPU and it will receive
once it is ready.
b) KVM_INTERRUPT_UNSET
This clears pending external interrupt for a virtual CPU.
This is an asynchronous vcpu ioctl and can be invoked from any thread.
LOONGARCH:
^^^^^^^^^^
Queues an external interrupt to be injected into the virtual CPU. A negative
interrupt number dequeues the interrupt.
This is an asynchronous vcpu ioctl and can be invoked from any thread.
4.18 KVM_GET_MSRS
643-682`KVM_GET_MSRS`는 x86에서 system ioctl과 vCPU ioctl 두 형태로 사용합니다. vCPU 형태는 basic이고 system 형태에는 `KVM_CAP_GET_MSR_FEATURES`가 필요합니다. 반환값은 성공적으로 읽은 MSR 수이며 error면 -1입니다.
System fd에서 호출하면 VM에 제공할 수 있는 MSR 기반 feature의 값을 읽습니다. `KVM_GET_SUPPORTED_CPUID`와 비슷하지만 CPUID leaf 대신 MSR index와 값을 반환하며, 읽을 수 있는 index 목록은 system ioctl `KVM_GET_MSR_FEATURE_INDEX_LIST`로 구합니다.
vCPU fd에서 호출하면 해당 vCPU의 model-specific register를 읽습니다. 지원되는 guest MSR index 목록은 system ioctl `KVM_GET_MSR_INDEX_LIST`로 구합니다.
Userspace는 `struct kvm_msrs.nmsrs`에 `entries` array 크기를 넣고 각 `kvm_msr_entry.index`를 채웁니다. KVM은 각 entry의 `data`를 채우며 `pad`와 `reserved` field는 ABI 구조를 보존합니다.
Type대상Index 목록
SystemVM에 제공 가능한 MSR feature`KVM_GET_MSR_FEATURE_INDEX_LIST`
vCPUvCPU model-specific register`KVM_GET_MSR_INDEX_LIST`
fd class에 따라 읽는 대상과 capability가 달라집니다.
4.18 KVM_GET_MSRS
-----------------
:Capability: basic (vcpu), KVM_CAP_GET_MSR_FEATURES (system)
:Architectures: x86
:Type: system ioctl, vcpu ioctl
:Parameters: struct kvm_msrs (in/out)
:Returns: number of msrs successfully returned;
-1 on error
When used as a system ioctl:
Reads the values of MSR-based features that are available for the VM. This
is similar to KVM_GET_SUPPORTED_CPUID, but it returns MSR indices and values.
The list of msr-based features can be obtained using KVM_GET_MSR_FEATURE_INDEX_LIST
in a system ioctl.
When used as a vcpu ioctl:
Reads model-specific registers from the vcpu. Supported msr indices can
be obtained using KVM_GET_MSR_INDEX_LIST in a system ioctl.
::
struct kvm_msrs {
__u32 nmsrs; /* number of msrs in entries */
__u32 pad;
struct kvm_msr_entry entries[0];
};
struct kvm_msr_entry {
__u32 index;
__u32 reserved;
__u64 data;
};
Application code should set the 'nmsrs' member (which indicates the
size of the entries array) and the 'index' member of each array entry.
kvm will fill in the 'data' member.
4.19 KVM_SET_MSRS
683-704`KVM_SET_MSRS`는 x86 basic vCPU ioctl이며 `struct kvm_msrs`로 model-specific register 값을 vCPU에 씁니다. Structure는 `KVM_GET_MSRS`와 같습니다.
Userspace는 `nmsrs`에 entries 수를 넣고 각 entry의 `index`와 `data`를 채웁니다. KVM은 `entries[]`를 앞에서부터 하나씩 설정합니다.
Reserved bit 설정, KVM이 지원하거나 emulate하지 않는 MSR 등으로 한 entry가 실패하면 즉시 처리를 중단합니다. 반환값은 그 전까지 성공적으로 설정한 MSR 수이고 ioctl 자체 error는 -1입니다. 따라서 요청 수보다 작은 비음수 값도 부분 성공으로 처리해야 합니다.
4.19 KVM_SET_MSRS
-----------------
:Capability: basic
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_msrs (in)
:Returns: number of msrs successfully set (see below), -1 on error
Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the
data structures.
Application code should set the 'nmsrs' member (which indicates the
size of the entries array), and the 'index' and 'data' members of each
array entry.
It tries to set the MSRs in array entries[] one by one. If setting an MSR
fails, e.g., due to setting reserved bits, the MSR isn't supported/emulated
by KVM, etc..., it stops processing the MSR list and returns the number of
MSRs that have been set successfully.
4.20 KVM_SET_CPUID
705-744`KVM_SET_CPUID`는 x86 basic vCPU ioctl이며 guest의 `cpuid` instruction 응답을 `struct kvm_cpuid`로 정의합니다. 가능한 경우 application은 더 새로운 `KVM_SET_CPUID2`를 사용해야 합니다.
이 ioctl이 실패하면 이전에 유효했던 CPUID configuration이 보존된다는 보장이 없습니다. 필요하면 `KVM_GET_CPUID2`로 실패 뒤 실제 configuration을 다시 읽어야 합니다.
`KVM_RUN` 뒤에 `KVM_SET_CPUID` 또는 `KVM_SET_CPUID2`로 guest vCPU model을 바꾸면 guest가 불안정해질 수 있습니다. APIC ID와 topology 등의 차이를 제외하고 vCPU마다 서로 다른 CPUID configuration을 쓰는 것도 불안정성을 유발할 수 있습니다.
`struct kvm_cpuid`의 `nent`는 `entries` 수입니다. 각 `kvm_cpuid_entry`는 `function`과 `eax`, `ebx`, `ecx`, `edx` 응답 및 padding을 담습니다.
상황주의점
ioctl 실패이전 CPUID state 보존 보장 없음
KVM_RUN 이후 변경Guest vCPU model 불안정 가능
vCPU별 이질적 설정Topology 예외 외 차이는 불안정 가능
실패와 실행 시점에 관한 보존 계약이 약하므로 userspace가 상태를 검증해야 합니다.
4.20 KVM_SET_CPUID
------------------
:Capability: basic
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_cpuid (in)
:Returns: 0 on success, -1 on error
Defines the vcpu responses to the cpuid instruction. Applications
should use the KVM_SET_CPUID2 ioctl if available.
Caveat emptor:
- If this IOCTL fails, KVM gives no guarantees that previous valid CPUID
configuration (if there is) is not corrupted. Userspace can get a copy
of the resulting CPUID configuration through KVM_GET_CPUID2 in case.
- Using KVM_SET_CPUID{,2} after KVM_RUN, i.e. changing the guest vCPU model
after running the guest, may cause guest instability.
- Using heterogeneous CPUID configurations, modulo APIC IDs, topology, etc...
may cause guest instability.
::
struct kvm_cpuid_entry {
__u32 function;
__u32 eax;
__u32 ebx;
__u32 ecx;
__u32 edx;
__u32 padding;
};
/* for KVM_SET_CPUID */
struct kvm_cpuid {
__u32 nent;
__u32 padding;
struct kvm_cpuid_entry entries[0];
};
4.21 KVM_SET_SIGNAL_MASK
745-770`KVM_SET_SIGNAL_MASK`는 모든 architecture의 basic vCPU ioctl이며 `KVM_RUN` 실행 중 block할 signal을 `struct kvm_signal_mask`로 정의합니다.
이 mask는 해당 thread의 signal mask를 임시로 override합니다. 전통적 동작을 유지하는 `SIGKILL`과 `SIGSTOP`을 제외하고 unblocked signal을 받으면 `KVM_RUN`이 `-EINTR`로 return합니다.
다만 원래 thread signal mask에서 block된 signal은 임시 KVM mask가 허용해도 전달되지 않습니다. Structure의 `len`은 뒤따르는 `sigset` byte array 길이를 나타냅니다.
4.21 KVM_SET_SIGNAL_MASK
------------------------
:Capability: basic
:Architectures: all
:Type: vcpu ioctl
:Parameters: struct kvm_signal_mask (in)
:Returns: 0 on success, -1 on error
Defines which signals are blocked during execution of KVM_RUN. This
signal mask temporarily overrides the threads signal mask. Any
unblocked signal received (except SIGKILL and SIGSTOP, which retain
their traditional behaviour) will cause KVM_RUN to return with -EINTR.
Note the signal will only be delivered if not blocked by the original
signal mask.
::
/* for KVM_SET_SIGNAL_MASK */
struct kvm_signal_mask {
__u32 len;
__u8 sigset[0];
};
4.22 KVM_GET_FPU
771-808`KVM_GET_FPU`는 x86과 LoongArch의 basic vCPU ioctl이며 vCPU floating-point state를 `struct kvm_fpu`에 읽습니다.
x86 layout은 여덟 x87 `fpr`, control/status word `fcw`와 `fsw`, fxsave 형식 `ftwx`, 마지막 opcode·instruction/data pointer, 16개 XMM register, `mxcsr`를 포함합니다.
LoongArch layout은 floating-point control/status `fcsr`, condition-code `fcc`, 32개 `kvm_fpureg`를 포함하고 각 register는 네 개의 64-bit slot으로 표현됩니다.
Architecture주요 state
x86x87 FPR, FCW/FSW, opcode/IP/DP, XMM, MXCSR
LoongArchFCSR, FCC, 32개 256-bit 표현 FPR
Architecture별 floating-point snapshot 구성입니다.
4.22 KVM_GET_FPU
----------------
:Capability: basic
:Architectures: x86, loongarch
:Type: vcpu ioctl
:Parameters: struct kvm_fpu (out)
:Returns: 0 on success, -1 on error
Reads the floating point state from the vcpu.
::
/* x86: for KVM_GET_FPU and KVM_SET_FPU */
struct kvm_fpu {
__u8 fpr[8][16];
__u16 fcw;
__u16 fsw;
__u8 ftwx; /* in fxsave format */
__u8 pad1;
__u16 last_opcode;
__u64 last_ip;
__u64 last_dp;
__u8 xmm[16][16];
__u32 mxcsr;
__u32 pad2;
};
/* LoongArch: for KVM_GET_FPU and KVM_SET_FPU */
struct kvm_fpu {
__u32 fcsr;
__u64 fcc;
struct kvm_fpureg {
__u64 val64[4];
}fpr[32];
};
4.23 KVM_SET_FPU
809-846`KVM_SET_FPU`는 x86과 LoongArch의 basic vCPU ioctl이며 입력 `struct kvm_fpu`를 vCPU floating-point state에 씁니다. 성공 시 0, 실패 시 -1입니다.
x86과 LoongArch structure layout은 바로 앞 `KVM_GET_FPU`와 동일하므로 migration이나 snapshot 복원 시 architecture에 맞는 전체 state를 제공해야 합니다.
4.23 KVM_SET_FPU
----------------
:Capability: basic
:Architectures: x86, loongarch
:Type: vcpu ioctl
:Parameters: struct kvm_fpu (in)
:Returns: 0 on success, -1 on error
Writes the floating point state to the vcpu.
::
/* x86: for KVM_GET_FPU and KVM_SET_FPU */
struct kvm_fpu {
__u8 fpr[8][16];
__u16 fcw;
__u16 fsw;
__u8 ftwx; /* in fxsave format */
__u8 pad1;
__u16 last_opcode;
__u64 last_ip;
__u64 last_dp;
__u8 xmm[16][16];
__u32 mxcsr;
__u32 pad2;
};
/* LoongArch: for KVM_GET_FPU and KVM_SET_FPU */
struct kvm_fpu {
__u32 fcsr;
__u64 fcc;
struct kvm_fpureg {
__u64 val64[4];
}fpr[32];
};
4.24 KVM_CREATE_IRQCHIP
847-868`KVM_CREATE_IRQCHIP`은 x86, arm64, s390의 VM ioctl이며 kernel 안에 interrupt controller model을 만듭니다. x86과 arm64에는 `KVM_CAP_IRQCHIP`, s390에는 `KVM_CAP_S390_IRQCHIP` capability가 적용됩니다.
x86에서는 virtual IOAPIC, 중첩된 두 PIC, 앞으로 생성할 vCPU의 local APIC를 구성합니다. GSI 0~15는 PIC와 IOAPIC 양쪽으로 route되고 GSI 16~23은 IOAPIC로만 갑니다.
arm64에서는 GICv2를 만듭니다. 다른 GIC version은 `KVM_CREATE_DEVICE`를 사용해야 하며 GICv2도 지원하므로 새 userspace는 이 방법을 선호해야 합니다.
s390에서는 dummy irq routing table을 만들며 호출 전에 VM capability `KVM_CAP_S390_IRQCHIP`을 enable해야 합니다.
Architecture생성되는 구성
x86IOAPIC, 두 PIC, vCPU local APIC
arm64GICv2; 다른 version은 KVM_CREATE_DEVICE
s390Dummy irq routing table
Architecture별 kernel interrupt-controller 구성이 다릅니다.
4.24 KVM_CREATE_IRQCHIP
-----------------------
:Capability: KVM_CAP_IRQCHIP, KVM_CAP_S390_IRQCHIP (s390)
:Architectures: x86, arm64, s390
:Type: vm ioctl
:Parameters: none
:Returns: 0 on success, -1 on error
Creates an interrupt controller model in the kernel.
On x86, creates a virtual ioapic, a virtual PIC (two PICs, nested), and sets up
future vcpus to have a local APIC. IRQ routing for GSIs 0-15 is set to both
PIC and IOAPIC; GSI 16-23 only go to the IOAPIC.
On arm64, a GICv2 is created. Any other GIC versions require the usage of
KVM_CREATE_DEVICE, which also supports creating a GICv2. Using
KVM_CREATE_DEVICE is preferred over KVM_CREATE_IRQCHIP for GICv2.
On s390, a dummy irq routing table is created.
Note that on s390 the KVM_CAP_S390_IRQCHIP vm capability needs to be enabled
before KVM_CREATE_IRQCHIP can be used.
4.25 KVM_IRQ_LINE
869-937`KVM_IRQ_LINE`은 x86과 arm64의 `KVM_CAP_IRQCHIP` VM ioctl이며 kernel interrupt controller model의 GSI 입력 level을 설정합니다. 일부 architecture에서는 먼저 `KVM_CREATE_IRQCHIP`을 호출해야 합니다.
Edge-triggered interrupt는 level을 1로 올린 뒤 다시 0으로 내려야 합니다. 실제 hardware pin의 active-low 또는 active-high polarity와 무관하게 `kvm_irq_level.level`에서 1은 asserted, 0은 deasserted를 뜻합니다.
x86은 과거 level-triggered interrupt polarity를 고려했지만 active-low 처리의 bitrot 때문에 이제 같은 1=active 규칙을 사용합니다. `KVM_CAP_X86_IOAPIC_POLARITY_IGNORED`가 이를 알리며, in-kernel irqchip을 사용한다면 이 capability 없이 guest에 active-low interrupt를 제시하지 않아야 합니다.
arm64는 CPU level 또는 in-kernel GIC에 interrupt를 보낼 수 있고 GIC의 특정 CPU용 PPI도 지정할 수 있습니다. `irq`의 bit 31~28은 `vcpu2_index`, 27~24는 `irq_type`, 23~16은 `vcpu_index`, 15~0은 `irq_id`입니다.
BitField의미
31..28`vcpu2_index`확장 vCPU index 상위 부분
27..24`irq_type`CPU, SPI, PPI 구분
23..16`vcpu_index`대상 vCPU index 하위 부분
15..0`irq_id`GIC interrupt ID
32-bit `irq` field의 원문 bit 배치를 구조화했습니다.
`KVM_ARM_IRQ_TYPE_CPU`는 out-of-kernel GIC에서 irq_id 0을 IRQ, 1을 FIQ로 해석합니다. `KVM_ARM_IRQ_TYPE_SPI`는 in-kernel GIC의 32~1019 SPI이며 `vcpu_index`를 무시합니다. `KVM_ARM_IRQ_TYPE_PPI`는 16~31 PPI입니다.
모든 arm64 유형에서 `level`은 line assert 또는 deassert에 사용됩니다. `KVM_CAP_ARM_IRQ_LINE_LAYOUT_2`가 있으면 대상 vCPU는 `256 * vcpu2_index + vcpu_index`이고, 없으면 `vcpu2_index`가 0이어야 합니다.
arm64의 `KVM_CAP_IRQCHIP`은 in-kernel irqchip에 대한 interrupt injection만 조건으로 삼습니다. Userspace interrupt controller를 사용할 때는 `KVM_IRQ_LINE`을 항상 사용할 수 있습니다.
`struct kvm_irq_level`은 GSI를 담는 `irq` 또는 사용하지 않는 `status` union과 0 또는 1인 `level`로 구성됩니다.
4.25 KVM_IRQ_LINE
-----------------
:Capability: KVM_CAP_IRQCHIP
:Architectures: x86, arm64
:Type: vm ioctl
:Parameters: struct kvm_irq_level
:Returns: 0 on success, -1 on error
Sets the level of a GSI input to the interrupt controller model in the kernel.
On some architectures it is required that an interrupt controller model has
been previously created with KVM_CREATE_IRQCHIP. Note that edge-triggered
interrupts require the level to be set to 1 and then back to 0.
On real hardware, interrupt pins can be active-low or active-high. This
does not matter for the level field of struct kvm_irq_level: 1 always
means active (asserted), 0 means inactive (deasserted).
x86 allows the operating system to program the interrupt polarity
(active-low/active-high) for level-triggered interrupts, and KVM used
to consider the polarity. However, due to bitrot in the handling of
active-low interrupts, the above convention is now valid on x86 too.
This is signaled by KVM_CAP_X86_IOAPIC_POLARITY_IGNORED. Userspace
should not present interrupts to the guest as active-low unless this
capability is present (or unless it is not using the in-kernel irqchip,
of course).
arm64 can signal an interrupt either at the CPU level, or at the
in-kernel irqchip (GIC), and for in-kernel irqchip can tell the GIC to
use PPIs designated for specific cpus. The irq field is interpreted
like this::
bits: | 31 ... 28 | 27 ... 24 | 23 ... 16 | 15 ... 0 |
field: | vcpu2_index | irq_type | vcpu_index | irq_id |
The irq_type field has the following values:
- KVM_ARM_IRQ_TYPE_CPU:
out-of-kernel GIC: irq_id 0 is IRQ, irq_id 1 is FIQ
- KVM_ARM_IRQ_TYPE_SPI:
in-kernel GIC: SPI, irq_id between 32 and 1019 (incl.)
(the vcpu_index field is ignored)
- KVM_ARM_IRQ_TYPE_PPI:
in-kernel GIC: PPI, irq_id between 16 and 31 (incl.)
(The irq_id field thus corresponds nicely to the IRQ ID in the ARM GIC specs)
In both cases, level is used to assert/deassert the line.
When KVM_CAP_ARM_IRQ_LINE_LAYOUT_2 is supported, the target vcpu is
identified as (256 * vcpu2_index + vcpu_index). Otherwise, vcpu2_index
must be zero.
Note that on arm64, the KVM_CAP_IRQCHIP capability only conditions
injection of interrupts for the in-kernel irqchip. KVM_IRQ_LINE can always
be used for a userspace interrupt controller.
::
struct kvm_irq_level {
union {
__u32 irq; /* GSI */
__s32 status; /* not used for KVM_IRQ_LEVEL */
};
__u32 level; /* 0 or 1 */
};
4.26 KVM_GET_IRQCHIP
938-962`KVM_GET_IRQCHIP`은 x86의 `KVM_CAP_IRQCHIP` VM ioctl입니다. `KVM_CREATE_IRQCHIP`으로 만든 kernel interrupt controller state를 caller가 제공한 `struct kvm_irqchip` buffer에 읽습니다.
`chip_id` 0은 PIC1, 1은 PIC2, 2는 IOAPIC입니다. Union은 512-byte reserved 공간 또는 `kvm_pic_state`, `kvm_ioapic_state`를 담습니다. 성공 시 0, 실패 시 -1입니다.
IDController
0PIC1
1PIC2
2IOAPIC
읽고 쓸 interrupt controller instance를 고릅니다.
4.26 KVM_GET_IRQCHIP
--------------------
:Capability: KVM_CAP_IRQCHIP
:Architectures: x86
:Type: vm ioctl
:Parameters: struct kvm_irqchip (in/out)
:Returns: 0 on success, -1 on error
Reads the state of a kernel interrupt controller created with
KVM_CREATE_IRQCHIP into a buffer provided by the caller.
::
struct kvm_irqchip {
__u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
__u32 pad;
union {
char dummy[512]; /* reserving space */
struct kvm_pic_state pic;
struct kvm_ioapic_state ioapic;
} chip;
};
4.27 KVM_SET_IRQCHIP
963-987`KVM_SET_IRQCHIP`은 x86의 `KVM_CAP_IRQCHIP` VM ioctl입니다. Caller가 제공한 `struct kvm_irqchip` state를 `KVM_CREATE_IRQCHIP`으로 만든 kernel interrupt controller에 씁니다.
Structure와 `chip_id` mapping은 `KVM_GET_IRQCHIP`과 동일합니다. Migration이나 snapshot 복원에서는 PIC1, PIC2, IOAPIC state를 각각 올바른 ID로 설정해야 합니다.
4.27 KVM_SET_IRQCHIP
--------------------
:Capability: KVM_CAP_IRQCHIP
:Architectures: x86
:Type: vm ioctl
:Parameters: struct kvm_irqchip (in)
:Returns: 0 on success, -1 on error
Sets the state of a kernel interrupt controller created with
KVM_CREATE_IRQCHIP from a buffer provided by the caller.
::
struct kvm_irqchip {
__u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
__u32 pad;
union {
char dummy[512]; /* reserving space */
struct kvm_pic_state pic;
struct kvm_ioapic_state ioapic;
} chip;
};
4.28 KVM_XEN_HVM_CONFIG
988-1037`KVM_XEN_HVM_CONFIG`는 x86의 `KVM_CAP_XEN_HVM` VM ioctl입니다. Xen HVM guest가 hypercall page를 초기화할 때 쓸 MSR과 userspace에 있는 32-bit·64-bit hypercall blob의 시작 주소와 크기를 설정합니다.
Guest가 해당 MSR에 쓰면 KVM은 현재 vCPU mode에 맞는 32-bit 또는 64-bit blob 한 page를 guest memory로 복사합니다.
MSR index는 hypervisor 용도로 비공식 예약된 `0x40000000`~`0x4fffffff` 범위여야 합니다. 경계 값은 `KVM_XEN_MSR_MIN_INDEX`와 `KVM_XEN_MSR_MAX_INDEX`로 정의됩니다.
`KVM_CAP_XEN_HVM` 조회 결과가 허용한 flag만 `kvm_xen_hvm_config.flags`에 넣을 수 있습니다.
`KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL`은 KVM이 hypercall page 내용을 자동 생성하게 합니다. Hypercall은 intercept되어 `KVM_EXIT_XEN`으로 userspace에 전달되며 이때 모든 blob size와 address field는 0이어야 합니다.
`KVM_XEN_HVM_CONFIG_EVTCHN_SEND`는 userspace가 guest `shared_info`를 직접 조작하지 않고 항상 `KVM_XEN_HVM_EVTCHN_SEND`로 event-channel interrupt를 전달하겠다는 뜻입니다. 그러면 KVM은 `SCHEDOP_poll` intercept 같은 최적화로 guest PV spinlock을 가속할 수 있습니다.
Capability가 ioctl을 광고했다면 이 상시 사용 flag를 보내지 않아도 userspace는 필요할 때 event 전달 ioctl을 사용할 수 있습니다. 현재 `struct kvm_xen_hvm_config`에는 그 밖의 flag가 유효하지 않습니다.
Flag계약
`INTERCEPT_HCALL`KVM이 page 생성, KVM_EXIT_XEN으로 전달, blob field는 0
`EVTCHN_SEND`Event channel을 항상 전용 ioctl로 전달
Capability 조회가 반환한 bit만 사용할 수 있습니다.
4.28 KVM_XEN_HVM_CONFIG
-----------------------
:Capability: KVM_CAP_XEN_HVM
:Architectures: x86
:Type: vm ioctl
:Parameters: struct kvm_xen_hvm_config (in)
:Returns: 0 on success, -1 on error
Sets the MSR that the Xen HVM guest uses to initialize its hypercall
page, and provides the starting address and size of the hypercall
blobs in userspace. When the guest writes the MSR, kvm copies one
page of a blob (32- or 64-bit, depending on the vcpu mode) to guest
memory.
The MSR index must be in the range [0x40000000, 0x4fffffff], i.e. must reside
in the range that is unofficially reserved for use by hypervisors. The min/max
values are enumerated via KVM_XEN_MSR_MIN_INDEX and KVM_XEN_MSR_MAX_INDEX.
::
struct kvm_xen_hvm_config {
__u32 flags;
__u32 msr;
__u64 blob_addr_32;
__u64 blob_addr_64;
__u8 blob_size_32;
__u8 blob_size_64;
__u8 pad2[30];
};
If certain flags are returned from the KVM_CAP_XEN_HVM check, they may
be set in the flags field of this ioctl:
The KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL flag requests KVM to generate
the contents of the hypercall page automatically; hypercalls will be
intercepted and passed to userspace through KVM_EXIT_XEN. In this
case, all of the blob size and address fields must be zero.
The KVM_XEN_HVM_CONFIG_EVTCHN_SEND flag indicates to KVM that userspace
will always use the KVM_XEN_HVM_EVTCHN_SEND ioctl to deliver event
channel interrupts rather than manipulating the guest's shared_info
structures directly. This, in turn, may allow KVM to enable features
such as intercepting the SCHEDOP_poll hypercall to accelerate PV
spinlock operation for the guest. Userspace may still use the ioctl
to deliver events if it was advertised, even if userspace does not
send this indication that it will always do so
No other flags are currently valid in the struct kvm_xen_hvm_config.
4.29 KVM_GET_CLOCK
1038-1087`KVM_GET_CLOCK`은 x86의 `KVM_CAP_ADJUST_CLOCK` VM ioctl이며 현재 guest가 보는 kvmclock timestamp를 `struct kvm_clock_data`에 읽습니다. `KVM_SET_CLOCK`과 함께 migration 같은 상황에서 clock monotonicity를 유지하는 데 사용합니다.
`KVM_CHECK_EXTENSION(KVM_CAP_ADJUST_CLOCK)`의 반환값은 KVM이 `kvm_clock_data.flags`에 반환할 수 있는 bit 집합입니다.
`KVM_CLOCK_TSC_STABLE`이 set이면 `clock`은 호출 순간 모든 vCPU가 보는 정확한 kvmclock 값입니다. Clear이면 `CLOCK_MONOTONIC`에 일정 offset을 더한 값이며 `KVM_SET_CLOCK`으로 offset을 바꿀 수 있습니다. Host TSC가 불안정하므로 vCPU마다 실제 읽는 값은 다를 수 있습니다.
`KVM_CLOCK_REALTIME`이 set이면 호출 순간 host realtime clocksource가 `realtime` field에 들어갑니다. Clear이면 이 field에 유효한 값이 없습니다.
`KVM_CLOCK_HOST_TSC`가 set이면 호출 순간 host timestamp counter가 `host_tsc` field에 들어갑니다. Clear이면 이 field에 유효한 값이 없습니다.
Flag유효한 정보
`KVM_CLOCK_TSC_STABLE`모든 vCPU가 공유하는 정확한 clock snapshot
`KVM_CLOCK_REALTIME``realtime` field
`KVM_CLOCK_HOST_TSC``host_tsc` field
각 bit는 함께 반환된 field의 유효성을 설명합니다.
Structure에는 `clock`, `flags`, `realtime`, `host_tsc`와 향후 확장을 위한 padding이 있습니다.
4.29 KVM_GET_CLOCK
------------------
:Capability: KVM_CAP_ADJUST_CLOCK
:Architectures: x86
:Type: vm ioctl
:Parameters: struct kvm_clock_data (out)
:Returns: 0 on success, -1 on error
Gets the current timestamp of kvmclock as seen by the current guest. In
conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios
such as migration.
When KVM_CAP_ADJUST_CLOCK is passed to KVM_CHECK_EXTENSION, it returns the
set of bits that KVM can return in struct kvm_clock_data's flag member.
The following flags are defined:
KVM_CLOCK_TSC_STABLE
If set, the returned value is the exact kvmclock
value seen by all VCPUs at the instant when KVM_GET_CLOCK was called.
If clear, the returned value is simply CLOCK_MONOTONIC plus a constant
offset; the offset can be modified with KVM_SET_CLOCK. KVM will try
to make all VCPUs follow this clock, but the exact value read by each
VCPU could differ, because the host TSC is not stable.
KVM_CLOCK_REALTIME
If set, the `realtime` field in the kvm_clock_data
structure is populated with the value of the host's real time
clocksource at the instant when KVM_GET_CLOCK was called. If clear,
the `realtime` field does not contain a value.
KVM_CLOCK_HOST_TSC
If set, the `host_tsc` field in the kvm_clock_data
structure is populated with the value of the host's timestamp counter (TSC)
at the instant when KVM_GET_CLOCK was called. If clear, the `host_tsc` field
does not contain a value.
::
struct kvm_clock_data {
__u64 clock; /* kvmclock current value */
__u32 flags;
__u32 pad0;
__u64 realtime;
__u64 host_tsc;
__u32 pad[4];
};
4.30 KVM_SET_CLOCK
1088-1120`KVM_SET_CLOCK`은 x86의 `KVM_CAP_ADJUST_CLOCK` VM ioctl이며 `struct kvm_clock_data.clock`에 지정한 값으로 현재 kvmclock timestamp를 설정합니다. `KVM_GET_CLOCK`과 함께 migration 시 monotonicity를 유지합니다.
`KVM_CLOCK_REALTIME` flag를 주면 KVM은 입력 `realtime`과 호출 순간 host realtime clocksource를 비교합니다. 그 사이 흐른 시간의 차이를 guest에 제공할 최종 kvmclock 값에 더합니다.
`KVM_GET_CLOCK`이 반환하는 다른 flag도 입력으로 허용되지만 무시됩니다. 따라서 복원 경로는 의미가 정의된 `KVM_CLOCK_REALTIME`만 clock 계산에 영향을 준다고 보아야 합니다.
입력 structure layout은 `KVM_GET_CLOCK`과 같으며 `clock`, `flags`, `realtime`, `host_tsc`, padding을 포함합니다. 성공 시 0, 실패 시 -1입니다.
4.30 KVM_SET_CLOCK
------------------
:Capability: KVM_CAP_ADJUST_CLOCK
:Architectures: x86
:Type: vm ioctl
:Parameters: struct kvm_clock_data (in)
:Returns: 0 on success, -1 on error
Sets the current timestamp of kvmclock to the value specified in its parameter.
In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenarios
such as migration.
The following flags can be passed:
KVM_CLOCK_REALTIME
If set, KVM will compare the value of the `realtime` field
with the value of the host's real time clocksource at the instant when
KVM_SET_CLOCK was called. The difference in elapsed time is added to the final
kvmclock value that will be provided to guests.
Other flags returned by ``KVM_GET_CLOCK`` are accepted but ignored.
::
struct kvm_clock_data {
__u64 clock; /* kvmclock current value */
__u32 flags;
__u32 pad0;
__u64 realtime;
__u64 host_tsc;
__u32 pad[4];
};4.31 KVM_GET_VCPU_EVENTS
1121-1248`KVM_GET_VCPU_EVENTS`는 x86과 arm64의 `KVM_CAP_VCPU_EVENTS` vCPU ioctl이며 현재 pending event state를 읽습니다. `KVM_CAP_INTR_SHADOW`가 기능을 확장합니다.
x86에서는 pending exception, interrupt, NMI와 관련 state를 반환합니다. Exception에는 injection·pending 여부, vector 번호, error code와 payload가 있고 interrupt에는 injection·soft·shadow state, NMI에는 injection·pending·masked state가 있습니다. SIPI vector와 SMI/SMM state도 함께 저장됩니다.
Flag유효한 state
`KVM_VCPUEVENT_VALID_SHADOW``interrupt.shadow`
`KVM_VCPUEVENT_VALID_SMM``smi` sub-structure
`KVM_VCPUEVENT_VALID_PAYLOAD`Exception payload와 pending
`KVM_VCPUEVENT_VALID_TRIPLE_FAULT`Triple-fault pending state
각 flag는 대응 field가 유효한 snapshot임을 나타냅니다.
arm64에서 kernel이 emulate하는 device access가 실제 hardware라면 physical SError를 만들 상황이면 KVM은 virtual SError를 pending으로 둘 수 있습니다. 이 state는 guest가 `PSTATE.A`를 unmask해 exception을 받을 때까지 유지됩니다.
vCPU 실행은 pending SError를 전달하거나 새 SError를 만들 수 있으므로 event 설명은 vCPU가 실행 중이 아닐 때만 유효합니다. GET/SET API는 guest-visible register와 함께 이 숨은 state를 저장·복원·migration하는 수단이며 이미 pending인 SError를 취소할 수는 없습니다.
Userspace device가 SError를 만들 때는 먼저 현재 event를 읽어 기존 pending SError가 없는지 확인해야 합니다. 이미 있으면 Arm RAS의 Multiple SError 규칙을 따라야 합니다.
`KVM_CAP_ARM_INJECT_SERROR_ESR`가 있으면 read 시 `serror_has_esr`가 set되며 injector는 `serror_esr` 하위 24-bit ISS를 지정합니다. Capability가 있는데 `has_esr`를 0으로 쓰면 KVM이 ESR을 고릅니다. Capability 없이 `has_esr`를 지정하거나 ESR 상위 bit를 설정하면 `-EINVAL`입니다.
Pending external abort는 virtual CPU로 바로 전달되므로 다시 읽을 수 없습니다. 초기화되지 않은 vCPU에서 호출하면 `-ENOEXEC`입니다.
Field의미
`serror_pending`Virtual SError pending
`serror_has_esr`ESR 값 유효
`ext_dabt_pending`External data abort pending
`serror_esr`SError ESR, userspace 지정은 ISS 하위 24-bit
Migration에 필요한 비가시 exception state입니다.
4.31 KVM_GET_VCPU_EVENTS
------------------------
:Capability: KVM_CAP_VCPU_EVENTS
:Extended by: KVM_CAP_INTR_SHADOW
:Architectures: x86, arm64
:Type: vcpu ioctl
:Parameters: struct kvm_vcpu_events (out)
:Returns: 0 on success, -1 on error
X86:
^^^^
Gets currently pending exceptions, interrupts, and NMIs as well as related
states of the vcpu.
::
struct kvm_vcpu_events {
struct {
__u8 injected;
__u8 nr;
__u8 has_error_code;
__u8 pending;
__u32 error_code;
} exception;
struct {
__u8 injected;
__u8 nr;
__u8 soft;
__u8 shadow;
} interrupt;
struct {
__u8 injected;
__u8 pending;
__u8 masked;
__u8 pad;
} nmi;
__u32 sipi_vector;
__u32 flags;
struct {
__u8 smm;
__u8 pending;
__u8 smm_inside_nmi;
__u8 latched_init;
} smi;
__u8 reserved[27];
__u8 exception_has_payload;
__u64 exception_payload;
};
The following bits are defined in the flags field:
- KVM_VCPUEVENT_VALID_SHADOW may be set to signal that
interrupt.shadow contains a valid state.
- KVM_VCPUEVENT_VALID_SMM may be set to signal that smi contains a
valid state.
- KVM_VCPUEVENT_VALID_PAYLOAD may be set to signal that the
exception_has_payload, exception_payload, and exception.pending
fields contain a valid state. This bit will be set whenever
KVM_CAP_EXCEPTION_PAYLOAD is enabled.
- KVM_VCPUEVENT_VALID_TRIPLE_FAULT may be set to signal that the
triple_fault_pending field contains a valid state. This bit will
be set whenever KVM_CAP_X86_TRIPLE_FAULT_EVENT is enabled.
ARM64:
^^^^^^
If the guest accesses a device that is being emulated by the host kernel in
such a way that a real device would generate a physical SError, KVM may make
a virtual SError pending for that VCPU. This system error interrupt remains
pending until the guest takes the exception by unmasking PSTATE.A.
Running the VCPU may cause it to take a pending SError, or make an access that
causes an SError to become pending. The event's description is only valid while
the VPCU is not running.
This API provides a way to read and write the pending 'event' state that is not
visible to the guest. To save, restore or migrate a VCPU the struct representing
the state can be read then written using this GET/SET API, along with the other
guest-visible registers. It is not possible to 'cancel' an SError that has been
made pending.
A device being emulated in user-space may also wish to generate an SError. To do
this the events structure can be populated by user-space. The current state
should be read first, to ensure no existing SError is pending. If an existing
SError is pending, the architecture's 'Multiple SError interrupts' rules should
be followed. (2.5.3 of DDI0587.a "ARM Reliability, Availability, and
Serviceability (RAS) Specification").
SError exceptions always have an ESR value. Some CPUs have the ability to
specify what the virtual SError's ESR value should be. These systems will
advertise KVM_CAP_ARM_INJECT_SERROR_ESR. In this case exception.has_esr will
always have a non-zero value when read, and the agent making an SError pending
should specify the ISS field in the lower 24 bits of exception.serror_esr. If
the system supports KVM_CAP_ARM_INJECT_SERROR_ESR, but user-space sets the events
with exception.has_esr as zero, KVM will choose an ESR.
Specifying exception.has_esr on a system that does not support it will return
-EINVAL. Setting anything other than the lower 24bits of exception.serror_esr
will return -EINVAL.
It is not possible to read back a pending external abort (injected via
KVM_SET_VCPU_EVENTS or otherwise) because such an exception is always delivered
directly to the virtual CPU).
Calling this ioctl on a vCPU that hasn't been initialized will return
-ENOEXEC.
::
struct kvm_vcpu_events {
struct {
__u8 serror_pending;
__u8 serror_has_esr;
__u8 ext_dabt_pending;
/* Align it to 8 bytes */
__u8 pad[5];
__u64 serror_esr;
} exception;
__u32 reserved[12];
};
4.32 KVM_SET_VCPU_EVENTS
1249-1317`KVM_SET_VCPU_EVENTS`는 x86과 arm64의 `KVM_CAP_VCPU_EVENTS` vCPU ioctl이며 `KVM_GET_VCPU_EVENTS`와 같은 structure로 pending event state를 설정합니다.
x86에서 실행 중 비동기로 바뀔 수 있는 `nmi.pending`, `sipi_vector`, `smi.smm`, `smi.pending`은 대응 valid flag를 clear해 update에서 제외할 수 있습니다. 이렇게 하면 현재 kernel state를 덮어쓰지 않습니다.
Flag전송 대상
`KVM_VCPUEVENT_VALID_NMI_PENDING``nmi.pending`
`KVM_VCPUEVENT_VALID_SIPI_VECTOR``sipi_vector`
`KVM_VCPUEVENT_VALID_SMM``smi` sub-structure
Set된 valid bit만 해당 state를 kernel로 옮깁니다.
`KVM_CAP_INTR_SHADOW`가 있으면 `VALID_SHADOW`로 interrupt shadow를 쓸 수 있습니다. `VALID_SMM`은 `KVM_CAP_X86_SMM`이 있을 때만, `VALID_PAYLOAD`는 `KVM_CAP_EXCEPTION_PAYLOAD`가 enable됐을 때, triple-fault state는 `KVM_CAP_X86_TRIPLE_FAULT_EVENT`가 enable됐을 때 사용합니다.
arm64에서는 pending SError를 설정할 수 있지만 이미 pending이 된 SError를 취소할 수 없습니다.
Guest I/O memory access를 userspace가 처리하지 못한 `KVM_EXIT_MMIO` 또는 `KVM_EXIT_ARM_NISV` 뒤에는 `KVM_CAP_ARM_INJECT_EXT_DABT`가 있을 때 `ext_dabt_pending`으로 fault address의 external abort injection을 요청할 수 있습니다. 다른 exit 뒤 이를 set하는 것은 programming error입니다.
이 helper는 userspace 구현 간 실패 access 보고 방식을 통일합니다. 개별 register를 `KVM_SET_ONE_REG`로 조작하면 모든 Arm exception을 직접 emulate할 수도 있습니다. 초기화되지 않은 vCPU에서는 `-ENOEXEC`입니다.
4.32 KVM_SET_VCPU_EVENTS
------------------------
:Capability: KVM_CAP_VCPU_EVENTS
:Extended by: KVM_CAP_INTR_SHADOW
:Architectures: x86, arm64
:Type: vcpu ioctl
:Parameters: struct kvm_vcpu_events (in)
:Returns: 0 on success, -1 on error
X86:
^^^^
Set pending exceptions, interrupts, and NMIs as well as related states of the
vcpu.
See KVM_GET_VCPU_EVENTS for the data structure.
Fields that may be modified asynchronously by running VCPUs can be excluded
from the update. These fields are nmi.pending, sipi_vector, smi.smm,
smi.pending. Keep the corresponding bits in the flags field cleared to
suppress overwriting the current in-kernel state. The bits are:
=============================== ==================================
KVM_VCPUEVENT_VALID_NMI_PENDING transfer nmi.pending to the kernel
KVM_VCPUEVENT_VALID_SIPI_VECTOR transfer sipi_vector
KVM_VCPUEVENT_VALID_SMM transfer the smi sub-struct.
=============================== ==================================
If KVM_CAP_INTR_SHADOW is available, KVM_VCPUEVENT_VALID_SHADOW can be set in
the flags field to signal that interrupt.shadow contains a valid state and
shall be written into the VCPU.
KVM_VCPUEVENT_VALID_SMM can only be set if KVM_CAP_X86_SMM is available.
If KVM_CAP_EXCEPTION_PAYLOAD is enabled, KVM_VCPUEVENT_VALID_PAYLOAD
can be set in the flags field to signal that the
exception_has_payload, exception_payload, and exception.pending fields
contain a valid state and shall be written into the VCPU.
If KVM_CAP_X86_TRIPLE_FAULT_EVENT is enabled, KVM_VCPUEVENT_VALID_TRIPLE_FAULT
can be set in flags field to signal that the triple_fault field contains
a valid state and shall be written into the VCPU.
ARM64:
^^^^^^
User space may need to inject several types of events to the guest.
Set the pending SError exception state for this VCPU. It is not possible to
'cancel' an Serror that has been made pending.
If the guest performed an access to I/O memory which could not be handled by
userspace, for example because of missing instruction syndrome decode
information or because there is no device mapped at the accessed IPA, then
userspace can ask the kernel to inject an external abort using the address
from the exiting fault on the VCPU. It is a programming error to set
ext_dabt_pending after an exit which was not either KVM_EXIT_MMIO or
KVM_EXIT_ARM_NISV. This feature is only available if the system supports
KVM_CAP_ARM_INJECT_EXT_DABT. This is a helper which provides commonality in
how userspace reports accesses for the above cases to guests, across different
userspace implementations. Nevertheless, userspace can still emulate all Arm
exceptions by manipulating individual registers using the KVM_SET_ONE_REG API.
See KVM_GET_VCPU_EVENTS for the data structure.
Calling this ioctl on a vCPU that hasn't been initialized will return
-ENOEXEC.
4.33 KVM_GET_DEBUGREGS
1318-1339`KVM_GET_DEBUGREGS`는 x86의 `KVM_CAP_DEBUGREGS` vCPU ioctl이며 vCPU debug register를 읽습니다.
`struct kvm_debugregs`는 네 breakpoint address register `db[4]`, status `dr6`, control `dr7`, flags와 향후 확장을 위한 `reserved[9]`를 담습니다.
4.33 KVM_GET_DEBUGREGS
----------------------
:Capability: KVM_CAP_DEBUGREGS
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_debugregs (out)
:Returns: 0 on success, -1 on error
Reads debug registers from the vcpu.
::
struct kvm_debugregs {
__u64 db[4];
__u64 dr6;
__u64 dr7;
__u64 flags;
__u64 reserved[9];
};
4.34 KVM_SET_DEBUGREGS
1340-1354`KVM_SET_DEBUGREGS`는 같은 x86 debug-register structure를 vCPU에 씁니다. 성공 시 0, 실패 시 -1입니다.
`flags` field는 아직 사용되지 않으므로 입력에서 반드시 0으로 clear해야 합니다.
4.34 KVM_SET_DEBUGREGS
----------------------
:Capability: KVM_CAP_DEBUGREGS
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_debugregs (in)
:Returns: 0 on success, -1 on error
Writes debug registers into the vcpu.
See KVM_GET_DEBUGREGS for the data structure. The flags field is unused
yet and must be cleared on entry.
4.35 KVM_SET_USER_MEMORY_REGION
1355-1436`KVM_SET_USER_MEMORY_REGION`은 모든 architecture의 `KVM_CAP_USER_MEMORY` VM ioctl이며 guest physical memory slot을 생성·수정·삭제합니다.
`slot` bit 0~15는 VM별 user memory slot ID이고 `KVM_CAP_NR_MEMSLOTS`보다 작아야 합니다. 같은 guest physical address space의 slot은 겹칠 수 없습니다.
`KVM_CAP_MULTI_ADDRESS_SPACE`가 있으면 `slot` bit 16~31이 address-space ID입니다. 이 값은 capability 조회 결과보다 작아야 하며 overlap 제한은 각 address space 안에서만 적용됩니다.
`memory_size`를 0으로 주면 slot을 삭제합니다. 기존 slot은 guest physical address를 옮기거나 flag를 바꿀 수 있지만 크기를 변경할 수 없습니다.
`userspace_addr`는 slot 전체 크기에 걸쳐 접근 가능한 untagged userspace memory를 가리켜야 합니다. Anonymous memory, 일반 file, hugetlbfs 등 어떤 object도 backing이 될 수 있습니다.
Guest와 host 양쪽에서 large page를 쓰기 쉽게 하려면 `guest_phys_addr`와 `userspace_addr`의 하위 21-bit를 같게 맞추는 것이 권장됩니다.
Flag동작
`KVM_MEM_LOG_DIRTY_PAGES`Slot write를 추적해 KVM_GET_DIRTY_LOG로 조회
`KVM_MEM_READONLY`Capability가 허용하면 read-only; write는 KVM_EXIT_MMIO
Memory tracking과 write protection을 선택합니다.
`KVM_CAP_SYNC_MMU`가 있으면 backing을 바꾸는 `mmap()`이나 `madvise(MADV_DROP)` 같은 변화가 guest mapping에 자동으로 즉시 반영됩니다.
TDX guest는 region 삭제·이동 시 guest memory 내용을 잃고 read-only region과 address-space ID 0 이외를 지원하지 않습니다.
arm64에서 read-only slot의 page-table walker write는 `KVM_EXIT_MMIO`를 만들지 않습니다. KVM이 walker가 쓸 data를 제공할 수 없어 emulate가 불가능하므로 원인이 load/store면 data abort, instruction fetch면 instruction abort를 guest에 inject합니다.
s390 UCONTROL VM에서는 `-EINVAL` 또는 `-EEXIST`, protected VM에서는 `-EINVAL`을 반환합니다.
작업규칙
생성고유 slot ID, 비중첩 GPA 범위
이동허용
Flag 변경허용
Resize허용하지 않음
삭제`memory_size = 0`
Create, update, delete 경로의 핵심 제약입니다.
4.35 KVM_SET_USER_MEMORY_REGION
-------------------------------
:Capability: KVM_CAP_USER_MEMORY
:Architectures: all
:Type: vm ioctl
:Parameters: struct kvm_userspace_memory_region (in)
:Returns: 0 on success, -1 on error
::
struct kvm_userspace_memory_region {
__u32 slot;
__u32 flags;
__u64 guest_phys_addr;
__u64 memory_size; /* bytes */
__u64 userspace_addr; /* start of the userspace allocated memory */
};
/* for kvm_userspace_memory_region::flags */
#define KVM_MEM_LOG_DIRTY_PAGES (1UL << 0)
#define KVM_MEM_READONLY (1UL << 1)
This ioctl allows the user to create, modify or delete a guest physical
memory slot. Bits 0-15 of "slot" specify the slot id and this value
should be less than the maximum number of user memory slots supported per
VM. The maximum allowed slots can be queried using KVM_CAP_NR_MEMSLOTS.
Slots may not overlap in guest physical address space.
If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 of "slot"
specifies the address space which is being modified. They must be
less than the value that KVM_CHECK_EXTENSION returns for the
KVM_CAP_MULTI_ADDRESS_SPACE capability. Slots in separate address spaces
are unrelated; the restriction on overlapping slots only applies within
each address space.
Deleting a slot is done by passing zero for memory_size. When changing
an existing slot, it may be moved in the guest physical memory space,
or its flags may be modified, but it may not be resized.
Memory for the region is taken starting at the address denoted by the
field userspace_addr, which must point at user addressable memory for
the entire memory slot size. Any object may back this memory, including
anonymous memory, ordinary files, and hugetlbfs.
On architectures that support a form of address tagging, userspace_addr must
be an untagged address.
It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr
be identical. This allows large pages in the guest to be backed by large
pages in the host.
The flags field supports two flags: KVM_MEM_LOG_DIRTY_PAGES and
KVM_MEM_READONLY. The former can be set to instruct KVM to keep track of
writes to memory within the slot. See KVM_GET_DIRTY_LOG ioctl to know how to
use it. The latter can be set, if KVM_CAP_READONLY_MEM capability allows it,
to make a new slot read-only. In this case, writes to this memory will be
posted to userspace as KVM_EXIT_MMIO exits.
When the KVM_CAP_SYNC_MMU capability is available, changes in the backing of
the memory region are automatically reflected into the guest. For example, an
mmap() that affects the region will be made visible immediately. Another
example is madvise(MADV_DROP).
For TDX guest, deleting/moving memory region loses guest memory contents.
Read only region isn't supported. Only as-id 0 is supported.
Note: On arm64, a write generated by the page-table walker (to update
the Access and Dirty flags, for example) never results in a
KVM_EXIT_MMIO exit when the slot has the KVM_MEM_READONLY flag. This
is because KVM cannot provide the data that would be written by the
page-table walker, making it impossible to emulate the access.
Instead, an abort (data abort if the cause of the page-table update
was a load or a store, instruction abort if it was an instruction
fetch) is injected in the guest.
S390:
^^^^^
Returns -EINVAL or -EEXIST if the VM has the KVM_VM_S390_UCONTROL flag set.
Returns -EINVAL if called on a protected VM.
4.36 KVM_SET_TSS_ADDR
1437-1458`KVM_SET_TSS_ADDR`는 x86의 `KVM_CAP_SET_TSS_ADDR` VM ioctl이며 guest physical address space에서 3-page 영역의 시작 주소를 정합니다.
영역은 첫 4GB 안에 있어야 하고 memory slot이나 MMIO address와 충돌하면 안 됩니다. Guest가 이 영역에 접근하면 오동작할 수 있습니다.
Intel virtualization 구현의 hardware quirk 때문에 Intel 기반 host에서는 이 ioctl이 필수입니다.
4.36 KVM_SET_TSS_ADDR
---------------------
:Capability: KVM_CAP_SET_TSS_ADDR
:Architectures: x86
:Type: vm ioctl
:Parameters: unsigned long tss_address (in)
:Returns: 0 on success, -1 on error
This ioctl defines the physical address of a three-page region in the guest
physical address space. The region must be within the first 4GB of the
guest physical address space and must not conflict with any memory slot
or any mmio address. The guest may malfunction if it accesses this memory
region.
This ioctl is required on Intel-based hosts. This is needed on Intel hardware
because of a quirk in the virtualization implementation (see the internals
documentation when it pops into existence).
.. _KVM_ENABLE_CAP:
4.37 KVM_ENABLE_CAP
1459-1513`KVM_ENABLE_CAP`은 기본 enable이 아닌 KVM extension을 guest에 활성화합니다. vCPU별 capability는 vCPU fd, VM 전체 capability는 VM fd에서 호출합니다.
vCPU 형태는 MIPS, PowerPC, s390, x86, LoongArch에서 `KVM_CAP_ENABLE_CAP`으로 제공되고 VM 형태는 모든 architecture에서 `KVM_CAP_ENABLE_CAP_VM`으로 제공됩니다.
지원하지 않는 system에서는 항상 실패하며 지원하는 system도 enable 가능한 extension에만 동작합니다. 먼저 `KVM_CHECK_EXTENSION`으로 capability와 enable 가능 여부를 확인해야 합니다.
`struct kvm_enable_cap.cap`은 활성화할 capability입니다. `flags`는 미래 확장용 bit field로 현재 반드시 0이어야 하며, feature가 초기값을 요구하면 `args[4]`에 넣습니다. `pad[64]`는 ABI 확장 공간입니다.
범위ioctl fd
vCPU-specificvCPU fd
VM-wideVM fd
Capability ownership에 맞는 fd를 선택합니다.
4.37 KVM_ENABLE_CAP
-------------------
:Capability: KVM_CAP_ENABLE_CAP
:Architectures: mips, ppc, s390, x86, loongarch
:Type: vcpu ioctl
:Parameters: struct kvm_enable_cap (in)
:Returns: 0 on success; -1 on error
:Capability: KVM_CAP_ENABLE_CAP_VM
:Architectures: all
:Type: vm ioctl
:Parameters: struct kvm_enable_cap (in)
:Returns: 0 on success; -1 on error
.. note::
Not all extensions are enabled by default. Using this ioctl the application
can enable an extension, making it available to the guest.
On systems that do not support this ioctl, it always fails. On systems that
do support it, it only works for extensions that are supported for enablement.
To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should
be used.
::
struct kvm_enable_cap {
/* in */
__u32 cap;
The capability that is supposed to get enabled.
::
__u32 flags;
A bitfield indicating future enhancements. Has to be 0 for now.
::
__u64 args[4];
Arguments for enabling a feature. If a feature needs initial values to
function properly, this is the place to put them.
::
__u8 pad[64];
};
The vcpu ioctl should be used for vcpu-specific capabilities, the vm ioctl
for vm-wide capabilities.
4.38 KVM_GET_MP_STATE
1514-1594`KVM_GET_MP_STATE`는 x86, s390, arm64, RISC-V, LoongArch의 `KVM_CAP_MP_STATE` vCPU ioctl이며 uniprocessor guest에도 유효한 현재 multiprocessing state를 반환합니다.
State의미
`RUNNABLE`실행 가능; x86, arm64, RISC-V, LoongArch
`UNINITIALIZED`INIT를 받지 않은 x86 AP
`INIT_RECEIVED`INIT 뒤 SIPI 대기 x86
`HALTED`HLT 뒤 interrupt 대기 x86
`SIPI_RECEIVED`SIPI를 막 받은 x86
`STOPPED`정지; s390, arm64, RISC-V
`CHECK_STOP`s390 특별 error state
`OPERATING`s390 실행 또는 halt
`LOAD`s390 load/startup state
`SUSPENDED`arm64 wakeup event 대기
State별 의미와 주요 적용 architecture입니다.
x86에서는 `KVM_CREATE_IRQCHIP` 뒤에만 이 ioctl이 유용합니다. In-kernel irqchip이 없으면 userspace가 MP state를 관리해야 합니다.
arm64 `SUSPENDED` state에서 KVM은 WFI instruction의 architectural execution을 emulate합니다. Wakeup을 인식하면 `KVM_SYSTEM_EVENT_WAKEUP`으로 userspace에 exit하고, userspace가 wakeup을 수용하려면 state를 `RUNNABLE`로 바꿔야 합니다.
`SUSPENDED`를 유지한다면 interrupt masking 등으로 wakeup 원인을 억제해야 반복 `KVM_RUN`이 즉시 exit하며 CPU를 낭비하는 일을 막을 수 있습니다. 다시 `RUNNABLE`로 바꿀 때는 억제를 위해 바꾼 state도 원래대로 복원해야 합니다.
RISC-V에서는 `STOPPED`와 `RUNNABLE`만 유효하고 LoongArch에서는 runnable 여부를 나타내는 `RUNNABLE`만 사용합니다.
4.38 KVM_GET_MP_STATE
---------------------
:Capability: KVM_CAP_MP_STATE
:Architectures: x86, s390, arm64, riscv, loongarch
:Type: vcpu ioctl
:Parameters: struct kvm_mp_state (out)
:Returns: 0 on success; -1 on error
::
struct kvm_mp_state {
__u32 mp_state;
};
Returns the vcpu's current "multiprocessing state" (though also valid on
uniprocessor guests).
Possible values are:
========================== ===============================================
KVM_MP_STATE_RUNNABLE the vcpu is currently running
[x86,arm64,riscv,loongarch]
KVM_MP_STATE_UNINITIALIZED the vcpu is an application processor (AP)
which has not yet received an INIT signal [x86]
KVM_MP_STATE_INIT_RECEIVED the vcpu has received an INIT signal, and is
now ready for a SIPI [x86]
KVM_MP_STATE_HALTED the vcpu has executed a HLT instruction and
is waiting for an interrupt [x86]
KVM_MP_STATE_SIPI_RECEIVED the vcpu has just received a SIPI (vector
accessible via KVM_GET_VCPU_EVENTS) [x86]
KVM_MP_STATE_STOPPED the vcpu is stopped [s390,arm64,riscv]
KVM_MP_STATE_CHECK_STOP the vcpu is in a special error state [s390]
KVM_MP_STATE_OPERATING the vcpu is operating (running or halted)
[s390]
KVM_MP_STATE_LOAD the vcpu is in a special load/startup state
[s390]
KVM_MP_STATE_SUSPENDED the vcpu is in a suspend state and is waiting
for a wakeup event [arm64]
========================== ===============================================
On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an
in-kernel irqchip, the multiprocessing state must be maintained by userspace on
these architectures.
For arm64:
^^^^^^^^^^
If a vCPU is in the KVM_MP_STATE_SUSPENDED state, KVM will emulate the
architectural execution of a WFI instruction.
If a wakeup event is recognized, KVM will exit to userspace with a
KVM_SYSTEM_EVENT exit, where the event type is KVM_SYSTEM_EVENT_WAKEUP. If
userspace wants to honor the wakeup, it must set the vCPU's MP state to
KVM_MP_STATE_RUNNABLE. If it does not, KVM will continue to await a wakeup
event in subsequent calls to KVM_RUN.
.. warning::
If userspace intends to keep the vCPU in a SUSPENDED state, it is
strongly recommended that userspace take action to suppress the
wakeup event (such as masking an interrupt). Otherwise, subsequent
calls to KVM_RUN will immediately exit with a KVM_SYSTEM_EVENT_WAKEUP
event and inadvertently waste CPU cycles.
Additionally, if userspace takes action to suppress a wakeup event,
it is strongly recommended that it also restores the vCPU to its
original state when the vCPU is made RUNNABLE again. For example,
if userspace masked a pending interrupt to suppress the wakeup,
the interrupt should be unmasked before returning control to the
guest.
For riscv:
^^^^^^^^^^
The only states that are valid are KVM_MP_STATE_STOPPED and
KVM_MP_STATE_RUNNABLE which reflect if the vcpu is paused or not.
On LoongArch, only the KVM_MP_STATE_RUNNABLE state is used to reflect
whether the vcpu is runnable.
4.39 KVM_SET_MP_STATE
1595-1619`KVM_SET_MP_STATE`는 `KVM_GET_MP_STATE`와 같은 architecture 및 structure로 vCPU multiprocessing state를 설정합니다.
x86에서는 in-kernel irqchip을 만든 뒤에만 유용하며, arm64와 RISC-V는 `STOPPED`와 `RUNNABLE`만 허용합니다. LoongArch는 runnable 여부를 나타내는 `RUNNABLE`만 사용합니다.
4.39 KVM_SET_MP_STATE
---------------------
:Capability: KVM_CAP_MP_STATE
:Architectures: x86, s390, arm64, riscv, loongarch
:Type: vcpu ioctl
:Parameters: struct kvm_mp_state (in)
:Returns: 0 on success; -1 on error
Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for
arguments.
On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an
in-kernel irqchip, the multiprocessing state must be maintained by userspace on
these architectures.
For arm64/riscv:
^^^^^^^^^^^^^^^^
The only states that are valid are KVM_MP_STATE_STOPPED and
KVM_MP_STATE_RUNNABLE which reflect if the vcpu should be paused or not.
On LoongArch, only the KVM_MP_STATE_RUNNABLE state is used to reflect
whether the vcpu is runnable.
4.40 KVM_SET_IDENTITY_MAP_ADDR
1620-1643`KVM_SET_IDENTITY_MAP_ADDR`는 x86의 `KVM_CAP_SET_IDENTITY_MAP_ADDR` VM ioctl이며 guest physical address space에서 한 page짜리 identity-map 보조 영역의 주소를 정합니다.
주소는 첫 4GB 안에 있고 memory slot 및 MMIO와 충돌하지 않아야 합니다. 0을 지정하면 default `0xfffbc000`으로 reset합니다.
Intel virtualization quirk 때문에 Intel host에서 필요하며, 어떤 vCPU라도 이미 생성된 뒤에는 실패합니다.
4.40 KVM_SET_IDENTITY_MAP_ADDR
------------------------------
:Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR
:Architectures: x86
:Type: vm ioctl
:Parameters: unsigned long identity (in)
:Returns: 0 on success, -1 on error
This ioctl defines the physical address of a one-page region in the guest
physical address space. The region must be within the first 4GB of the
guest physical address space and must not conflict with any memory slot
or any mmio address. The guest may malfunction if it accesses this memory
region.
Setting the address to 0 will result in resetting the address to its default
(0xfffbc000).
This ioctl is required on Intel-based hosts. This is needed on Intel hardware
because of a quirk in the virtualization implementation (see the internals
documentation when it pops into existence).
Fails if any VCPU has already been created.
4.41 KVM_SET_BOOT_CPU_ID
1644-1658`KVM_SET_BOOT_CPU_ID`는 x86의 `KVM_CAP_SET_BOOT_CPU_ID` VM ioctl이며 Bootstrap Processor가 될 vCPU를 `KVM_CREATE_VCPU`와 같은 ID로 지정합니다.
호출하지 않으면 vCPU 0이 기본 BSP입니다. 반드시 vCPU 생성 전에 호출해야 하며 그 뒤에는 `EBUSY`를 반환합니다.
4.41 KVM_SET_BOOT_CPU_ID
------------------------
:Capability: KVM_CAP_SET_BOOT_CPU_ID
:Architectures: x86
:Type: vm ioctl
:Parameters: unsigned long vcpu_id
:Returns: 0 on success, -1 on error
Define which vcpu is the Bootstrap Processor (BSP). Values are the same
as the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the default
is vcpu 0. This ioctl has to be called before vcpu creation,
otherwise it will return EBUSY error.
4.42 KVM_GET_XSAVE
1659-1678`KVM_GET_XSAVE`는 x86의 `KVM_CAP_XSAVE` vCPU ioctl이며 현재 vCPU XSAVE state를 userspace `struct kvm_xsave`로 복사합니다.
기본 structure는 1,024개의 32-bit word인 `region`으로 4,096 byte를 이루고 뒤에 가변 확장을 나타내는 `extra[0]`가 있습니다.
4.42 KVM_GET_XSAVE
------------------
:Capability: KVM_CAP_XSAVE
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_xsave (out)
:Returns: 0 on success, -1 on error
::
struct kvm_xsave {
__u32 region[1024];
__u32 extra[0];
};
This ioctl would copy current vcpu's xsave struct to the userspace.
4.43 KVM_SET_XSAVE
1679-1706`KVM_SET_XSAVE`는 x86에서 `KVM_CAP_XSAVE`와 `KVM_CAP_XSAVE2`를 사용하는 vCPU ioctl이며 userspace XSAVE state를 kernel vCPU에 복사합니다.
복사 크기는 VM fd에서 `KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2)`가 반환한 byte 수이며 항상 최소 4,096입니다. 현재는 `arch_prctl()`로 dynamic feature를 enable했을 때만 더 크지만 이 조건은 향후 바뀔 수 있습니다.
`struct kvm_xsave` 내부 state-save area offset은 host CPUID leaf `0xD`의 내용을 따릅니다. Userspace는 고정 layout을 가정하지 말고 host가 광고한 offset과 크기를 사용해야 합니다.
4.43 KVM_SET_XSAVE
------------------
:Capability: KVM_CAP_XSAVE and KVM_CAP_XSAVE2
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_xsave (in)
:Returns: 0 on success, -1 on error
::
struct kvm_xsave {
__u32 region[1024];
__u32 extra[0];
};
This ioctl would copy userspace's xsave struct to the kernel. It copies
as many bytes as are returned by KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2),
when invoked on the vm file descriptor. The size value returned by
KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2) will always be at least 4096.
Currently, it is only greater than 4096 if a dynamic feature has been
enabled with ``arch_prctl()``, but this may change in the future.
The offsets of the state save areas in struct kvm_xsave follow the
contents of CPUID leaf 0xD on the host.
4.44 KVM_GET_XCRS
1707-1733`KVM_GET_XCRS`는 x86의 `KVM_CAP_XCRS` vCPU ioctl이며 현재 vCPU extended control register를 userspace로 복사합니다.
각 `kvm_xcr`은 register 번호 `xcr`, reserved field, 64-bit `value`를 담습니다. `kvm_xcrs`는 유효 entry 수 `nr_xcrs`, flags, 최대 `KVM_MAX_XCRS` entries와 padding으로 구성됩니다.
4.44 KVM_GET_XCRS
-----------------
:Capability: KVM_CAP_XCRS
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_xcrs (out)
:Returns: 0 on success, -1 on error
::
struct kvm_xcr {
__u32 xcr;
__u32 reserved;
__u64 value;
};
struct kvm_xcrs {
__u32 nr_xcrs;
__u32 flags;
struct kvm_xcr xcrs[KVM_MAX_XCRS];
__u64 padding[16];
};
This ioctl would copy current vcpu's xcrs to the userspace.
4.45 KVM_SET_XCRS
1734-1760`KVM_SET_XCRS`는 x86의 `KVM_CAP_XCRS` vCPU ioctl이며 `struct kvm_xcrs`에 지정한 extended control register 값을 vCPU에 설정합니다.
Structure layout은 `KVM_GET_XCRS`와 같으며 userspace는 `nr_xcrs`만큼의 register 번호와 64-bit 값을 제공합니다. 성공 시 0, 실패 시 -1입니다.
4.45 KVM_SET_XCRS
-----------------
:Capability: KVM_CAP_XCRS
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_xcrs (in)
:Returns: 0 on success, -1 on error
::
struct kvm_xcr {
__u32 xcr;
__u32 reserved;
__u64 value;
};
struct kvm_xcrs {
__u32 nr_xcrs;
__u32 flags;
struct kvm_xcr xcrs[KVM_MAX_XCRS];
__u64 padding[16];
};
This ioctl would set vcpu's xcr to the value userspace specified.
4.46 KVM_GET_SUPPORTED_CPUID
1761-1852`KVM_GET_SUPPORTED_CPUID`는 x86의 `KVM_CAP_EXT_CPUID` system ioctl이며 hardware와 기본 KVM configuration 양쪽이 지원하는 CPUID feature를 반환합니다.
Userspace는 이 결과를 바탕으로 hardware·kernel·userspace capability 및 사용자 요구와 일치하는 `KVM_SET_CPUID2` 입력을 구성할 수 있습니다. 예를 들어 오래된 CPU를 emulate하거나 cluster 전체 feature를 동일하게 제한할 수 있습니다.
Dynamic feature bit는 ioctl 전에 `arch_prctl()`로 요청해야 결과에 포함됩니다. `KVM_CAP_X86_DISABLE_EXITS`처럼 기본 configuration 밖 feature를 노출하는 capability를 enable했다면 userspace가 결과를 알맞게 수정해야 합니다.
`kvm_cpuid2.nent`가 필요한 entry 수보다 작으면 `E2BIG`, 너무 크면 실제 크기로 조정한 뒤 `ENOMEM`을 반환합니다. 정확하면 유효 entry 수로 조정하고 array를 채웁니다.
반환 entry는 host CPUID에서 알 수 없거나 지원하지 않는 feature를 mask한 값입니다. x2APIC처럼 host CPU에 없어도 KVM이 효율적으로 emulate할 수 있어 노출되는 feature도 있습니다.
Field의미
`function`CPUID EAX 입력
`index`ECX 영향을 받는 leaf의 ECX 입력
`SIGNIFCANT_INDEX`Index field 유효
`eax`~`edx`해당 function/index 결과
CPUID function/index 조합과 결과 register를 표현합니다.
x2APIC와 TSC deadline timer는 true로 반환될 수 있지만 in-kernel local APIC emulation에는 `KVM_CREATE_IRQCHIP`이 필요합니다. TSC deadline은 `KVM_CAP_TSC_DEADLINE_TIMER`로도 확인하며 userspace가 직접 emulate할 때도 CPUID에 enable할 수 있습니다.
KVM은 x2APIC MSR access를 userspace로 forward하지 않으므로 `KVM_SET_CPUID2`에서 x2APIC을 enable하려면 반드시 `KVM_CREATE_IRQCHIP`을 사용해야 합니다.
nent결과
부족`E2BIG`
과다실제 수로 조정 후 `ENOMEM`
정확실제 entry 수와 data 반환
Variable-size entries 협상 규칙입니다.
4.46 KVM_GET_SUPPORTED_CPUID
----------------------------
:Capability: KVM_CAP_EXT_CPUID
:Architectures: x86
:Type: system ioctl
:Parameters: struct kvm_cpuid2 (in/out)
:Returns: 0 on success, -1 on error
::
struct kvm_cpuid2 {
__u32 nent;
__u32 padding;
struct kvm_cpuid_entry2 entries[0];
};
#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0)
#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1) /* deprecated */
#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2) /* deprecated */
struct kvm_cpuid_entry2 {
__u32 function;
__u32 index;
__u32 flags;
__u32 eax;
__u32 ebx;
__u32 ecx;
__u32 edx;
__u32 padding[3];
};
This ioctl returns x86 cpuid features which are supported by both the
hardware and kvm in its default configuration. Userspace can use the
information returned by this ioctl to construct cpuid information (for
KVM_SET_CPUID2) that is consistent with hardware, kernel, and
userspace capabilities, and with user requirements (for example, the
user may wish to constrain cpuid to emulate older hardware, or for
feature consistency across a cluster).
Dynamically-enabled feature bits need to be requested with
``arch_prctl()`` before calling this ioctl. Feature bits that have not
been requested are excluded from the result.
Note that certain capabilities, such as KVM_CAP_X86_DISABLE_EXITS, may
expose cpuid features (e.g. MONITOR) which are not supported by kvm in
its default configuration. If userspace enables such capabilities, it
is responsible for modifying the results of this ioctl appropriately.
Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structure
with the 'nent' field indicating the number of entries in the variable-size
array 'entries'. If the number of entries is too low to describe the cpu
capabilities, an error (E2BIG) is returned. If the number is too high,
the 'nent' field is adjusted and an error (ENOMEM) is returned. If the
number is just right, the 'nent' field is adjusted to the number of valid
entries in the 'entries' array, which is then filled.
The entries returned are the host cpuid as returned by the cpuid instruction,
with unknown or unsupported features masked out. Some features (for example,
x2apic), may not be present in the host cpu, but are exposed by kvm if it can
emulate them efficiently. The fields in each entry are defined as follows:
function:
the eax value used to obtain the entry
index:
the ecx value used to obtain the entry (for entries that are
affected by ecx)
flags:
an OR of zero or more of the following:
KVM_CPUID_FLAG_SIGNIFCANT_INDEX:
if the index field is valid
eax, ebx, ecx, edx:
the values returned by the cpuid instruction for
this function/index combination
x2APIC (CPUID leaf 1, ecx[21) and TSC deadline timer (CPUID leaf 1, ecx[24])
may be returned as true, but they depend on KVM_CREATE_IRQCHIP for in-kernel
emulation of the local APIC. TSC deadline timer support is also reported via::
ioctl(KVM_CHECK_EXTENSION, KVM_CAP_TSC_DEADLINE_TIMER)
if that returns true and you use KVM_CREATE_IRQCHIP, or if you emulate the
feature in userspace, then you can enable the feature for KVM_SET_CPUID2.
Enabling x2APIC in KVM_SET_CPUID2 requires KVM_CREATE_IRQCHIP as KVM doesn't
support forwarding x2APIC MSR accesses to userspace, i.e. KVM does not support
emulating x2APIC in userspace.
4.47 KVM_PPC_GET_PVINFO
1853-1882`KVM_PPC_GET_PVINFO`는 PowerPC의 `KVM_CAP_PPC_GET_PVINFO` VM ioctl이며 device tree 등으로 guest에 전달해야 할 paravirtualization 정보를 VM context에서 읽습니다.
`hcall[4]`는 hypercall을 이루는 네 instruction을 정의합니다. 향후 structure에 정보가 추가되면 해당 정보의 존재를 알리는 bit가 `flags` bitmap에 추가됩니다.
현재 `KVM_PPC_PVINFO_FLAGS_EV_IDLE` bit는 host가 ePAPR idle hypercall을 지원함을 나타냅니다.
4.47 KVM_PPC_GET_PVINFO
-----------------------
:Capability: KVM_CAP_PPC_GET_PVINFO
:Architectures: ppc
:Type: vm ioctl
:Parameters: struct kvm_ppc_pvinfo (out)
:Returns: 0 on success, !0 on error
::
struct kvm_ppc_pvinfo {
__u32 flags;
__u32 hcall[4];
__u8 pad[108];
};
This ioctl fetches PV specific information that need to be passed to the guest
using the device tree or other means from vm context.
The hcall array defines 4 instructions that make up a hypercall.
If any additional field gets added to this structure later on, a bit for that
additional piece of information will be set in the flags bitmap.
The flags bitmap is defined as::
/* the host supports the ePAPR idle hcall
#define KVM_PPC_PVINFO_FLAGS_EV_IDLE (1<<0)
4.52 KVM_SET_GSI_ROUTING
1883-1999`KVM_SET_GSI_ROUTING`은 x86, s390, arm64의 `KVM_CAP_IRQ_ROUTING` VM ioctl이며 기존 table을 덮어써 GSI routing entry 전체를 설정합니다.
arm64에서 GSI routing은 `KVM_IRQFD`에만 적용되고 `KVM_IRQ_LINE`에는 적용되지 않습니다. Top-level `kvm_irq_routing.flags`는 현재 정의된 값이 없어 0이어야 합니다.
Type대상
`KVM_IRQ_ROUTING_IRQCHIP`In-kernel irqchip과 pin
`KVM_IRQ_ROUTING_MSI`MSI address/data
`KVM_IRQ_ROUTING_S390_ADAPTER`s390 adapter interrupt
`KVM_IRQ_ROUTING_HV_SINT`Hyper-V synthetic interrupt
`KVM_IRQ_ROUTING_XEN_EVTCHN`Xen event channel
각 entry union의 유효 member를 type으로 선택합니다.
s390 UCONTROL VM에서는 `KVM_IRQ_ROUTING_S390_ADAPTER` 추가가 `-EINVAL`로 거부됩니다.
MSI entry의 `KVM_MSI_VALID_DEVID`는 `devid`가 유효함을 뜻합니다. VM별 `KVM_CAP_MSI_DEVID`가 device ID 제공 요구를 광고하며 capability가 없으면 flag를 set하지 않아야 합니다.
유효한 MSI `devid`는 message를 쓴 device의 고유 identifier이며 PCI에서는 보통 하위 16-bit BDF입니다.
x86에서 `address_hi`는 `KVM_CAP_X2APIC_API`의 `USE_32BIT_IDS`가 enable될 때만 사용됩니다. 이때 bit 31~8은 destination ID의 같은 bit를 제공하고 bit 7~0은 0이어야 합니다.
s390 adapter route는 indicator·summary address와 offset 및 adapter ID를, Hyper-V route는 vCPU와 SINT를, Xen route는 port·vCPU·priority를 담습니다.
`KVM_CAP_XEN_HVM`에 `EVTCHN_2LEVEL` 지원 bit가 있으면 Xen event-channel routing이 가능합니다. 현재 priority field는 존재하지만 2-level delivery 값만 지원하며 FIFO 방식은 향후 추가될 수 있습니다.
Entry허용 flag
MSICapability가 요구하면 `KVM_MSI_VALID_DEVID`
그 외0
Entry별 flag 제약입니다.
4.52 KVM_SET_GSI_ROUTING
------------------------
:Capability: KVM_CAP_IRQ_ROUTING
:Architectures: x86 s390 arm64
:Type: vm ioctl
:Parameters: struct kvm_irq_routing (in)
:Returns: 0 on success, -1 on error
Sets the GSI routing table entries, overwriting any previously set entries.
On arm64, GSI routing has the following limitation:
- GSI routing does not apply to KVM_IRQ_LINE but only to KVM_IRQFD.
::
struct kvm_irq_routing {
__u32 nr;
__u32 flags;
struct kvm_irq_routing_entry entries[0];
};
No flags are specified so far, the corresponding field must be set to zero.
::
struct kvm_irq_routing_entry {
__u32 gsi;
__u32 type;
__u32 flags;
__u32 pad;
union {
struct kvm_irq_routing_irqchip irqchip;
struct kvm_irq_routing_msi msi;
struct kvm_irq_routing_s390_adapter adapter;
struct kvm_irq_routing_hv_sint hv_sint;
struct kvm_irq_routing_xen_evtchn xen_evtchn;
__u32 pad[8];
} u;
};
/* gsi routing entry types */
#define KVM_IRQ_ROUTING_IRQCHIP 1
#define KVM_IRQ_ROUTING_MSI 2
#define KVM_IRQ_ROUTING_S390_ADAPTER 3
#define KVM_IRQ_ROUTING_HV_SINT 4
#define KVM_IRQ_ROUTING_XEN_EVTCHN 5
On s390, adding a KVM_IRQ_ROUTING_S390_ADAPTER is rejected on ucontrol VMs with
error -EINVAL.
flags:
- KVM_MSI_VALID_DEVID: used along with KVM_IRQ_ROUTING_MSI routing entry
type, specifies that the devid field contains a valid value. The per-VM
KVM_CAP_MSI_DEVID capability advertises the requirement to provide
the device ID. If this capability is not available, userspace should
never set the KVM_MSI_VALID_DEVID flag as the ioctl might fail.
- zero otherwise
::
struct kvm_irq_routing_irqchip {
__u32 irqchip;
__u32 pin;
};
struct kvm_irq_routing_msi {
__u32 address_lo;
__u32 address_hi;
__u32 data;
union {
__u32 pad;
__u32 devid;
};
};
If KVM_MSI_VALID_DEVID is set, devid contains a unique device identifier
for the device that wrote the MSI message. For PCI, this is usually a
BDF identifier in the lower 16 bits.
On x86, address_hi is ignored unless the KVM_X2APIC_API_USE_32BIT_IDS
feature of KVM_CAP_X2APIC_API capability is enabled. If it is enabled,
address_hi bits 31-8 provide bits 31-8 of the destination id. Bits 7-0 of
address_hi must be zero.
::
struct kvm_irq_routing_s390_adapter {
__u64 ind_addr;
__u64 summary_addr;
__u64 ind_offset;
__u32 summary_offset;
__u32 adapter_id;
};
struct kvm_irq_routing_hv_sint {
__u32 vcpu;
__u32 sint;
};
struct kvm_irq_routing_xen_evtchn {
__u32 port;
__u32 vcpu;
__u32 priority;
};
When KVM_CAP_XEN_HVM includes the KVM_XEN_HVM_CONFIG_EVTCHN_2LEVEL bit
in its indication of supported features, routing to Xen event channels
is supported. Although the priority field is present, only the value
KVM_XEN_HVM_CONFIG_EVTCHN_2LEVEL is supported, which means delivery by
2 level event channels. FIFO event channel support may be added in
the future.
4.55 KVM_SET_TSC_KHZ
2000-2022`KVM_SET_TSC_KHZ`는 x86 virtual TSC frequency를 kHz 단위로 설정합니다. vCPU ioctl에는 `KVM_CAP_TSC_CONTROL`, VM ioctl에는 `KVM_CAP_VM_TSC_CONTROL`이 적용됩니다.
VM 형태는 이후 생성되는 vCPU의 초기 frequency를 정하며 vCPU 생성 전에만 허용됩니다.
TSC-protected confidential VM처럼 VM lifetime 동안 frequency를 한 번만 정하고 바꾸지 않는 경우 VM ioctl을 사용하고 vCPU ioctl은 지원하지 않습니다. TDX guest가 해당 예입니다.
4.55 KVM_SET_TSC_KHZ
--------------------
:Capability: KVM_CAP_TSC_CONTROL / KVM_CAP_VM_TSC_CONTROL
:Architectures: x86
:Type: vcpu ioctl / vm ioctl
:Parameters: virtual tsc_khz
:Returns: 0 on success, -1 on error
Specifies the tsc frequency for the virtual machine. The unit of the
frequency is KHz.
If the KVM_CAP_VM_TSC_CONTROL capability is advertised, this can also
be used as a vm ioctl to set the initial tsc frequency of subsequently
created vCPUs. Note, the vm ioctl is only allowed prior to creating vCPUs.
For TSC protected Confidential Computing (CoCo) VMs where TSC frequency
is configured once at VM scope and remains unchanged during VM's
lifetime, the vm ioctl should be used to configure the TSC frequency
and the vcpu ioctl is not supported.
Example of such CoCo VMs: TDX guests.
4.56 KVM_GET_TSC_KHZ
2023-2036`KVM_GET_TSC_KHZ`는 x86 guest의 virtual TSC frequency를 kHz 단위로 반환합니다. vCPU와 VM 형태는 각각 `KVM_CAP_GET_TSC_KHZ`, `KVM_CAP_VM_TSC_CONTROL`에 대응합니다.
Host TSC가 불안정하면 frequency 대신 error `-EIO`를 반환합니다.
4.56 KVM_GET_TSC_KHZ
--------------------
:Capability: KVM_CAP_GET_TSC_KHZ / KVM_CAP_VM_TSC_CONTROL
:Architectures: x86
:Type: vcpu ioctl / vm ioctl
:Parameters: none
:Returns: virtual tsc-khz on success, negative value on error
Returns the tsc frequency of the guest. The unit of the return value is
KHz. If the host has unstable tsc this ioctl returns -EIO instead as an
error.
4.57 KVM_GET_LAPIC
2037-2067`KVM_GET_LAPIC`은 x86의 `KVM_CAP_IRQCHIP` vCPU ioctl이며 0x400-byte Local APIC register image를 `kvm_lapic_state.regs`에 읽습니다. Format과 layout은 architecture manual을 따릅니다.
`KVM_X2APIC_API_USE_32BIT_IDS`가 enable되면 APIC ID register 형식은 `MSR_IA32_APICBASE`가 나타내는 vCPU APIC mode에 따릅니다.
x2APIC은 byte 32~35에 32-bit APIC ID를 저장합니다. xAPIC은 8-bit ID만 허용하며 APIC register bit 31~24, 즉 structure byte 35에 저장합니다.
이 mode-dependent 형식을 쓸 때는 `KVM_SET_MSR`로 `MSR_IA32_APICBASE`를 정한 뒤 `KVM_GET_LAPIC`을 호출해야 합니다. Capability feature가 disable되면 structure는 항상 xAPIC 형식입니다.
조건저장 형식
USE_32BIT_IDS + x2APICbytes 32~35 전체
USE_32BIT_IDS + xAPICbyte 35의 8-bit ID
Feature disabled항상 xAPIC 형식
x2APIC capability와 vCPU mode가 byte 해석을 결정합니다.
4.57 KVM_GET_LAPIC
------------------
:Capability: KVM_CAP_IRQCHIP
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_lapic_state (out)
:Returns: 0 on success, -1 on error
::
#define KVM_APIC_REG_SIZE 0x400
struct kvm_lapic_state {
char regs[KVM_APIC_REG_SIZE];
};
Reads the Local APIC registers and copies them into the input argument. The
data format and layout are the same as documented in the architecture manual.
If KVM_X2APIC_API_USE_32BIT_IDS feature of KVM_CAP_X2APIC_API is
enabled, then the format of APIC_ID register depends on the APIC mode
(reported by MSR_IA32_APICBASE) of its VCPU. x2APIC stores APIC ID in
the APIC_ID register (bytes 32-35). xAPIC only allows an 8-bit APIC ID
which is stored in bits 31-24 of the APIC register, or equivalently in
byte 35 of struct kvm_lapic_state's regs field. KVM_GET_LAPIC must then
be called after MSR_IA32_APICBASE has been set with KVM_SET_MSR.
If KVM_X2APIC_API_USE_32BIT_IDS feature is disabled, struct kvm_lapic_state
always uses xAPIC format.
4.58 KVM_SET_LAPIC
2068-2091`KVM_SET_LAPIC`은 x86의 `KVM_CAP_IRQCHIP` vCPU ioctl이며 입력 0x400-byte register image를 Local APIC state로 복사합니다.
APIC ID가 있는 byte 32~35의 형식은 `KVM_CAP_X2APIC_API` 상태와 vCPU APIC mode에 따라 달라지며 `KVM_GET_LAPIC`의 규칙을 그대로 따릅니다.
4.58 KVM_SET_LAPIC
------------------
:Capability: KVM_CAP_IRQCHIP
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_lapic_state (in)
:Returns: 0 on success, -1 on error
::
#define KVM_APIC_REG_SIZE 0x400
struct kvm_lapic_state {
char regs[KVM_APIC_REG_SIZE];
};
Copies the input argument into the Local APIC registers. The data format
and layout are the same as documented in the architecture manual.
The format of the APIC ID register (bytes 32-35 of struct kvm_lapic_state's
regs field) depends on the state of the KVM_CAP_X2APIC_API capability.
See the note in KVM_GET_LAPIC.
4.59 KVM_IOEVENTFD
2092-2137`KVM_IOEVENTFD`는 모든 architecture의 `KVM_CAP_IOEVENTFD` VM ioctl이며 legal guest PIO/MMIO address에 eventfd를 attach하거나 detach합니다. 등록 주소에 guest가 쓰면 VM exit 대신 제공된 event가 signal됩니다.
`addr`는 PIO/MMIO address, `len`은 0·1·2·4·8 byte, `fd`는 eventfd입니다. s390 virtio-ccw에서는 주소 대신 subchannel과 virtqueue tuple을 match합니다.
Flag동작
`DATAMATCH`Guest write 값이 `datamatch`와 같을 때만 signal
`PIO`주소를 port I/O로 해석
`DEASSIGN`기존 ioeventfd 해제
`VIRTIO_CCW_NOTIFY`s390 virtio-ccw notify tuple
등록·matching 방식을 선택합니다.
virtio-ccw에서는 `addr`가 subchannel ID, `datamatch`가 virtqueue index입니다.
`KVM_CAP_IOEVENTFD_ANY_LENGTH`가 있으면 length 0을 허용하고 kernel이 guest write 길이를 무시합니다. 특정 architecture에서 더 빠른 VM exit 경로를 쓸 수 있으며 속도 향상이 없어도 기능은 정상 동작합니다.
4.59 KVM_IOEVENTFD
------------------
:Capability: KVM_CAP_IOEVENTFD
:Architectures: all
:Type: vm ioctl
:Parameters: struct kvm_ioeventfd (in)
:Returns: 0 on success, !0 on error
This ioctl attaches or detaches an ioeventfd to a legal pio/mmio address
within the guest. A guest write in the registered address will signal the
provided event instead of triggering an exit.
::
struct kvm_ioeventfd {
__u64 datamatch;
__u64 addr; /* legal pio/mmio address */
__u32 len; /* 0, 1, 2, 4, or 8 bytes */
__s32 fd;
__u32 flags;
__u8 pad[36];
};
For the special case of virtio-ccw devices on s390, the ioevent is matched
to a subchannel/virtqueue tuple instead.
The following flags are defined::
#define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch)
#define KVM_IOEVENTFD_FLAG_PIO (1 << kvm_ioeventfd_flag_nr_pio)
#define KVM_IOEVENTFD_FLAG_DEASSIGN (1 << kvm_ioeventfd_flag_nr_deassign)
#define KVM_IOEVENTFD_FLAG_VIRTIO_CCW_NOTIFY \
(1 << kvm_ioeventfd_flag_nr_virtio_ccw_notify)
If datamatch flag is set, the event will be signaled only if the written value
to the registered address is equal to datamatch in struct kvm_ioeventfd.
For virtio-ccw devices, addr contains the subchannel id and datamatch the
virtqueue index.
With KVM_CAP_IOEVENTFD_ANY_LENGTH, a zero length ioeventfd is allowed, and
the kernel will ignore the length of guest write and may get a faster vmexit.
The speedup may only apply to specific architectures, but the ioeventfd will
work anyway.
4.60 KVM_DIRTY_TLB
2138-2173`KVM_DIRTY_TLB`는 PowerPC의 `KVM_CAP_SW_TLB` vCPU ioctl입니다. Userspace가 shared TLB entry를 바꿀 때마다 관련 vCPU의 다음 `KVM_RUN` 전에 호출해야 합니다.
`bitmap`은 userspace bit array 주소입니다. Bit 수는 마지막으로 성공한 `KVM_ENABLE_CAP(KVM_CAP_SW_TLB)`가 정한 총 TLB entry 수를 64의 배수로 올림한 값입니다.
각 bit는 shared TLB array와 같은 순서의 entry 하나에 대응합니다. Array는 little-endian bit order로 bit 0은 첫 byte 최하위 bit, bit 8은 둘째 byte 최하위 bit입니다.
`num_dirty`는 bitmap에서 set된 bit 수이며 KVM이 bitmap을 처리할지 전체 invalidation할지 정하는 performance hint입니다. 정확한 set-bit 수를 넣어야 합니다.
순서작업
1Userspace가 shared TLB entry 변경
2Bitmap bit와 `num_dirty` 갱신
3`KVM_DIRTY_TLB` 호출
4관련 vCPU에서 `KVM_RUN`
Shared software TLB 변경 뒤 필요한 순서입니다.
4.60 KVM_DIRTY_TLB
------------------
:Capability: KVM_CAP_SW_TLB
:Architectures: ppc
:Type: vcpu ioctl
:Parameters: struct kvm_dirty_tlb (in)
:Returns: 0 on success, -1 on error
::
struct kvm_dirty_tlb {
__u64 bitmap;
__u32 num_dirty;
};
This must be called whenever userspace has changed an entry in the shared
TLB, prior to calling KVM_RUN on the associated vcpu.
The "bitmap" field is the userspace address of an array. This array
consists of a number of bits, equal to the total number of TLB entries as
determined by the last successful call to ``KVM_ENABLE_CAP(KVM_CAP_SW_TLB)``,
rounded up to the nearest multiple of 64.
Each bit corresponds to one TLB entry, ordered the same as in the shared TLB
array.
The array is little-endian: the bit 0 is the least significant bit of the
first byte, bit 8 is the least significant bit of the second byte, etc.
This avoids any complications with differing word sizes.
The "num_dirty" field is a performance hint for KVM to determine whether it
should skip processing the bitmap and just invalidate everything. It must
be set to the number of set bits in the bitmap.
4.62 KVM_CREATE_SPAPR_TCE
2174-2212`KVM_CREATE_SPAPR_TCE`는 PowerPC의 `KVM_CAP_SPAPR_TCE` VM ioctl이며 PAPR virtual I/O용 IOMMU인 virtual TCE table을 만들고 이를 조작할 file descriptor를 반환합니다.
TCE table은 virtual I/O logical address를 guest physical address로 변환하고 scatter/gather 기능을 제공합니다. `liobn`은 logical I/O bus number, `window_size`는 table이 변환할 DMA window 크기이며 4KiB마다 64-bit TCE entry 하나가 생깁니다.
Guest가 생성된 `liobn`에 `H_PUT_TCE` hypercall을 실행하면 kernel이 real mode에서 table을 갱신합니다. 생성되지 않은 `liobn`의 call은 VM exit으로 userspace가 처리해야 합니다.
반환 fd를 `mmap(2)`하면 kernel이 처리한 `H_PUT_TCE` entry를 userspace가 읽을 수 있고 필요한 경우 table을 직접 갱신할 수도 있습니다.
KVM_CREATE_SPAPR_TCE로 liobn·DMA window 등록→Guest가 H_PUT_TCE 호출→등록 liobn이면 kernel real-mode 갱신→미등록 liobn이면 VM exit 후 userspace 처리
`liobn` 등록 여부에 따라 hypercall 처리 위치가 갈립니다.
4.62 KVM_CREATE_SPAPR_TCE
-------------------------
:Capability: KVM_CAP_SPAPR_TCE
:Architectures: powerpc
:Type: vm ioctl
:Parameters: struct kvm_create_spapr_tce (in)
:Returns: file descriptor for manipulating the created TCE table
This creates a virtual TCE (translation control entry) table, which
is an IOMMU for PAPR-style virtual I/O. It is used to translate
logical addresses used in virtual I/O into guest physical addresses,
and provides a scatter/gather capability for PAPR virtual I/O.
::
/* for KVM_CAP_SPAPR_TCE */
struct kvm_create_spapr_tce {
__u64 liobn;
__u32 window_size;
};
The liobn field gives the logical IO bus number for which to create a
TCE table. The window_size field specifies the size of the DMA window
which this TCE table will translate - the table will contain one 64
bit TCE entry for every 4kiB of the DMA window.
When the guest issues an H_PUT_TCE hcall on a liobn for which a TCE
table has been created using this ioctl(), the kernel will handle it
in real mode, updating the TCE table. H_PUT_TCE calls for other
liobns will cause a vm exit and must be handled by userspace.
The return value is a file descriptor which can be passed to mmap(2)
to map the created TCE table into userspace. This lets userspace read
the entries written by kernel-handled H_PUT_TCE calls, and also lets
userspace update the TCE table directly which is useful in some
circumstances.
4.64 KVM_NMI
2213-2239`KVM_NMI`는 x86의 `KVM_CAP_USER_NMI` vCPU ioctl이며 해당 thread의 vCPU에 NMI를 queue합니다.
`KVM_CREATE_IRQCHIP` 전에는 virtual CPU core와 virtual local APIC 사이 interface로 명확히 정의됩니다. IRQCHIP을 만든 뒤에는 이 interface가 kernel 안에서 완전히 emulate됩니다.
In-kernel irqchip과 함께 LINT1 input을 emulate하려면 vCPU를 pause하고 `KVM_GET_LAPIC`으로 LAPIC state를 읽은 뒤 LINT1 LVT 변경이 NMI를 queue하는지 검사합니다. 필요한 경우 `KVM_NMI`를 호출하고 vCPU를 resume합니다.
일부 guest는 debugging을 돕기 위해 LINT1 NMI input이 panic을 일으키도록 구성합니다.
vCPU pause→KVM_GET_LAPIC으로 local APIC state 읽기→LINT1 LVT가 NMI를 queue하는지 확인→필요하면 KVM_NMI 호출→vCPU resume
KVM_CREATE_IRQCHIP 뒤 userspace가 따라야 할 순서입니다.
4.64 KVM_NMI
------------
:Capability: KVM_CAP_USER_NMI
:Architectures: x86
:Type: vcpu ioctl
:Parameters: none
:Returns: 0 on success, -1 on error
Queues an NMI on the thread's vcpu. Note this is well defined only
when KVM_CREATE_IRQCHIP has not been called, since this is an interface
between the virtual cpu core and virtual local APIC. After KVM_CREATE_IRQCHIP
has been called, this interface is completely emulated within the kernel.
To use this to emulate the LINT1 input with KVM_CREATE_IRQCHIP, use the
following algorithm:
- pause the vcpu
- read the local APIC's state (KVM_GET_LAPIC)
- check whether changing LINT1 will queue an NMI (see the LVT entry for LINT1)
- if so, issue KVM_NMI
- resume the vcpu
Some guests configure the LINT1 NMI input to cause a panic, aiding in
debugging.
4.65 KVM_S390_UCAS_MAP
2240-2261`KVM_S390_UCAS_MAP`은 s390 `KVM_CAP_S390_UCONTROL` vCPU ioctl이며 userspace memory를 user-controlled vCPU address space에 mapping합니다.
`user_addr`에서 시작하는 `length` byte를 `vcpu_addr`부터 mapping합니다. `user_addr`, `vcpu_addr`, `length` 모두 1MiB 경계에 정렬되어야 하며 성공 시 0입니다.
Field의미
`user_addr`Source userspace address
`vcpu_addr`Target vCPU address
`length`Mapping length
입력 structure의 세 주소·크기 field입니다.
4.65 KVM_S390_UCAS_MAP
----------------------
:Capability: KVM_CAP_S390_UCONTROL
:Architectures: s390
:Type: vcpu ioctl
:Parameters: struct kvm_s390_ucas_mapping (in)
:Returns: 0 in case of success
The parameter is defined like this::
struct kvm_s390_ucas_mapping {
__u64 user_addr;
__u64 vcpu_addr;
__u64 length;
};
This ioctl maps the memory at "user_addr" with the length "length" to
the vcpu's address space starting at "vcpu_addr". All parameters need to
be aligned by 1 megabyte.
4.66 KVM_S390_UCAS_UNMAP
2262-2283`KVM_S390_UCAS_UNMAP`은 같은 s390 UCONTROL vCPU address space에서 `vcpu_addr`부터 `length`만큼 mapping을 제거합니다.
Structure는 MAP과 같지만 `user_addr`는 무시됩니다. 모든 parameter는 여전히 1MiB 정렬이어야 하며 성공 시 0입니다.
4.66 KVM_S390_UCAS_UNMAP
------------------------
:Capability: KVM_CAP_S390_UCONTROL
:Architectures: s390
:Type: vcpu ioctl
:Parameters: struct kvm_s390_ucas_mapping (in)
:Returns: 0 in case of success
The parameter is defined like this::
struct kvm_s390_ucas_mapping {
__u64 user_addr;
__u64 vcpu_addr;
__u64 length;
};
This ioctl unmaps the memory in the vcpu's address space starting at
"vcpu_addr" with the length "length". The field "user_addr" is ignored.
All parameters need to be aligned by 1 megabyte.
4.67 KVM_S390_VCPU_FAULT
2284-2301`KVM_S390_VCPU_FAULT`는 s390 `KVM_CAP_S390_UCONTROL` vCPU ioctl이며 입력 absolute address에 대한 page-table entry를 만듭니다.
User-controlled VM에서는 vCPU address space, 일반 VM에서는 VM address space에 entry를 만듭니다. Minor fault에만 동작하므로 먼저 userspace page table을 통해 대상 memory page에 접근해 두는 것이 권장됩니다.
이 호출은 user-controlled VM의 validity intercept를 처리할 때 `KVM_RUN` 전에 vCPU lowcore page를 fault-in하는 데 유용합니다.
4.67 KVM_S390_VCPU_FAULT
------------------------
:Capability: KVM_CAP_S390_UCONTROL
:Architectures: s390
:Type: vcpu ioctl
:Parameters: vcpu absolute address (in)
:Returns: 0 in case of success
This call creates a page table entry on the virtual cpu's address space
(for user controlled virtual machines) or the virtual machine's address
space (for regular virtual machines). This only works for minor faults,
thus it's recommended to access subject memory page via the user page
table upfront. This is useful to handle validity intercepts for user
controlled virtual machines to fault in the virtual cpu's lowcore pages
prior to calling the KVM_RUN ioctl.
4.68 KVM_SET_ONE_REG
2302-2926`KVM_SET_ONE_REG`는 모든 architecture의 `KVM_CAP_ONE_REG` vCPU ioctl이며 `kvm_one_reg.id`가 지정한 단일 register에 `addr`가 가리키는 값을 씁니다. `addr`의 대상 크기는 register ID에 encode된 width와 일치해야 합니다.
errno대표 의미
`ENOENT`해당 register 없음
`EINVAL`잘못된 ID·미지원 register 또는 s390 protected VM
`EPERM`arm64 vCPU finalize 전 허용되지 않는 접근
`EBUSY`RISC-V vCPU 실행 뒤 변경 불가 register
문서의 errno는 지표일 뿐 특정 상황의 정확한 반환값에 의존하면 안 됩니다.
Register ID 공간에는 architecture-neutral 영역과 architecture별 영역이 있고 각 영역은 고유 상수와 width를 사용합니다. 원문 표는 PowerPC와 MIPS의 구현 register 이름 및 32·64·128-bit 폭을 전부 열거합니다.
PowerPC 목록은 HIOR, debug address, performance monitor, FPR·VR·VSR, VPA, MMU/TLB, interrupt state, timebase, transactional-memory register 등을 포함합니다. FPR 0~31은 64-bit, VR/VSR과 TM VSR은 128-bit이며 control/status register는 정의에 따라 32 또는 64-bit입니다.
MIPS 목록은 GPR 0~31, HI·LO·PC, CP0 register, MAAR, timer control, 32/64-bit FPR, 128-bit MSA vector와 FPU/MSA control register를 포함합니다.
Architecture주요 prefix·group
ARM`0x4020/0x4030`, core·CP15·VFP·firmware
arm64`0x60x0`, core/FP-SIMD·system·SVE·firmware
MIPS`0x70x0`, core·CP0·MAAR·KVM control·FPU/MSA
RISC-V`0x80x0`, config·core·CSR·timer·F/D extension
LoongArch`0x9030`, CSR·KVM control
x86`0x2030`, MSR 및 KVM-defined register
원문 encoding의 architecture 및 group prefix를 요약합니다.
32-bit ARM은 lower 32-bit로 register를 mapping하고 그 상위 16-bit를 group type 또는 coprocessor number로 사용합니다. Core는 `kvm_regs` index, CP15는 CRn·CRm·opcode field, CCSIDR는 CSSELR, VFP는 register 번호, firmware pseudo-register는 16-bit 번호로 encode합니다.
arm64 core/FP-SIMD ID도 `kvm_regs`를 32-bit array로 본 index를 사용하며 access width는 member에 따라 32~128-bit입니다. X0~X30, SP, PC, PSTATE, EL1 state, V0~V31, FPSR, FPCR의 정확한 encoding과 member 대응은 원문 표에 보존됩니다.
SVE-enabled vCPU에서는 기존 V0~V31 encoding을 허용하지 않고 해당 SVE Zn register의 하위 128-bit로 같은 내용을 접근해야 합니다.
arm64 system register ID는 `op0`, `op1`, `CRn`, `CRm`, `op2`를 encode합니다. `KVM_REG_ARM_TIMER_CVAL`과 `KVM_REG_ARM_TIMER_CNT`는 과거 실수로 각각 CNTVCT_EL0와 CNTV_CVAL_EL0 encoding이 뒤바뀌었지만 ABI이므로 그대로 유지됩니다.
arm64 SVE는 Zn을 2,048-bit slice, Pn과 FFR을 256-bit slice로 접근합니다. `2048 * slice`가 `128 * max_vq` 이상이면 `ENOENT`이며 SVE가 enable된 vCPU에서만 접근할 수 있습니다.
`KVM_REG_ARM64_SVE_VLS`를 제외한 SVE register는 `KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE)` 뒤에만 접근할 수 있습니다. VLS pseudo-register는 `KVM_ARM_VCPU_INIT` 뒤부터 finalize 전까지 지원 vector-length bitset을 조회·조정합니다.
시점동작
VCPU_INIT 전VLS 접근 불가
VCPU_INIT 후Host 최적 set 조회, userspace 조정 가능
잘못된 length set`EINVAL`
VCPU_FINALIZE 후VLS write는 `EPERM`
Vector-length configuration의 변경 가능 시점을 정리합니다.
arm64 bitmap-feature firmware register는 guest에 보일 hypercall service bitset입니다. VM 초기화 시 지원 bit가 모두 set되고 userspace는 GET으로 가용 service를 읽은 뒤 SET으로 노출 subset을 고릅니다. 어떤 vCPU든 한 번 실행한 뒤에는 immutable하며 SET은 `-EBUSY`입니다.
MIPS core ID는 register index를, CP0 ID는 32/64-bit width와 reg/sel을 encode합니다. `ENTRYLO0/1`은 host·guest word size와 무관하게 RI/XI 및 PFNX를 포함한 MIPS64 형식입니다.
MIPS FPU register는 현재 guest FPU mode인 `Status.FR`과 `Config5.FRE`에 따라 guest가 보는 형식으로 접근하므로 mode를 바꾸면 값이 unpredictable해질 수 있습니다. 128-bit MSA vector는 FPU register와 overlap합니다.
RISC-V config register `isa`는 host ISA feature를 기본값으로 가지며 언제든 읽을 수 있지만 guest vCPU가 실행되기 전에만 쓸 수 있습니다.
RISC-V core group은 PC, integer ABI register와 privilege mode를 담고 CSR group은 `sstatus`, `sie`, `stvec`, `sscratch`, `sepc`, `scause`, `stval`, `sip`, `satp`를 담습니다.
Group내용
ConfigISA feature bitmap
CorePC, integer register, privilege mode
CSRSupervisor control/status
TimerFrequency, time, compare, on/off state
F extension32-bit f[0..31], fcsr
D extension64-bit f[0..31], 32-bit fcsr
Guest execution state를 기능별 structure index로 나눕니다.
RISC-V timer frequency는 read-only이며 time, compare, compare state를 함께 제공합니다. F extension은 single precision, D extension은 double precision floating-point state를 나타냅니다.
LoongArch는 lower 32-bit에 register를 mapping하고 상위 16-bit를 group type으로 사용합니다. CSR group은 guest CPU control/status, KVM control group은 vCPU counter 설정이나 reset 같은 KVM-defined 기능을 담당합니다.
x86 MSR ID는 `0x2030 0002` 뒤에 32-bit MSR 번호를 붙입니다. KVM-defined x86 register로는 `0x2030 0003 0000 0000`의 Shadow Stack Pointer `SSP`가 정의됩니다.
4.68 KVM_SET_ONE_REG
--------------------
:Capability: KVM_CAP_ONE_REG
:Architectures: all
:Type: vcpu ioctl
:Parameters: struct kvm_one_reg (in)
:Returns: 0 on success, negative value on failure
Errors:
====== ============================================================
ENOENT no such register
EINVAL invalid register ID, or no such register or used with VMs in
protected virtualization mode on s390
EPERM (arm64) register access not allowed before vcpu finalization
EBUSY (riscv) changing register value not allowed after the vcpu
has run at least once
====== ============================================================
(These error codes are indicative only: do not rely on a specific error
code being returned in a specific situation.)
::
struct kvm_one_reg {
__u64 id;
__u64 addr;
};
Using this ioctl, a single vcpu register can be set to a specific value
defined by user space with the passed in struct kvm_one_reg, where id
refers to the register identifier as described below and addr is a pointer
to a variable with the respective size. There can be architecture agnostic
and architecture specific registers. Each have their own range of operation
and their own constants and width. To keep track of the implemented
registers, find a list below:
======= =============================== ============
Arch Register Width (bits)
======= =============================== ============
PPC KVM_REG_PPC_HIOR 64
PPC KVM_REG_PPC_IAC1 64
PPC KVM_REG_PPC_IAC2 64
PPC KVM_REG_PPC_IAC3 64
PPC KVM_REG_PPC_IAC4 64
PPC KVM_REG_PPC_DAC1 64
PPC KVM_REG_PPC_DAC2 64
PPC KVM_REG_PPC_DABR 64
PPC KVM_REG_PPC_DSCR 64
PPC KVM_REG_PPC_PURR 64
PPC KVM_REG_PPC_SPURR 64
PPC KVM_REG_PPC_DAR 64
PPC KVM_REG_PPC_DSISR 32
PPC KVM_REG_PPC_AMR 64
PPC KVM_REG_PPC_UAMOR 64
PPC KVM_REG_PPC_MMCR0 64
PPC KVM_REG_PPC_MMCR1 64
PPC KVM_REG_PPC_MMCRA 64
PPC KVM_REG_PPC_MMCR2 64
PPC KVM_REG_PPC_MMCRS 64
PPC KVM_REG_PPC_MMCR3 64
PPC KVM_REG_PPC_SIAR 64
PPC KVM_REG_PPC_SDAR 64
PPC KVM_REG_PPC_SIER 64
PPC KVM_REG_PPC_SIER2 64
PPC KVM_REG_PPC_SIER3 64
PPC KVM_REG_PPC_PMC1 32
PPC KVM_REG_PPC_PMC2 32
PPC KVM_REG_PPC_PMC3 32
PPC KVM_REG_PPC_PMC4 32
PPC KVM_REG_PPC_PMC5 32
PPC KVM_REG_PPC_PMC6 32
PPC KVM_REG_PPC_PMC7 32
PPC KVM_REG_PPC_PMC8 32
PPC KVM_REG_PPC_FPR0 64
...
PPC KVM_REG_PPC_FPR31 64
PPC KVM_REG_PPC_VR0 128
...
PPC KVM_REG_PPC_VR31 128
PPC KVM_REG_PPC_VSR0 128
...
PPC KVM_REG_PPC_VSR31 128
PPC KVM_REG_PPC_FPSCR 64
PPC KVM_REG_PPC_VSCR 32
PPC KVM_REG_PPC_VPA_ADDR 64
PPC KVM_REG_PPC_VPA_SLB 128
PPC KVM_REG_PPC_VPA_DTL 128
PPC KVM_REG_PPC_EPCR 32
PPC KVM_REG_PPC_EPR 32
PPC KVM_REG_PPC_TCR 32
PPC KVM_REG_PPC_TSR 32
PPC KVM_REG_PPC_OR_TSR 32
PPC KVM_REG_PPC_CLEAR_TSR 32
PPC KVM_REG_PPC_MAS0 32
PPC KVM_REG_PPC_MAS1 32
PPC KVM_REG_PPC_MAS2 64
PPC KVM_REG_PPC_MAS7_3 64
PPC KVM_REG_PPC_MAS4 32
PPC KVM_REG_PPC_MAS6 32
PPC KVM_REG_PPC_MMUCFG 32
PPC KVM_REG_PPC_TLB0CFG 32
PPC KVM_REG_PPC_TLB1CFG 32
PPC KVM_REG_PPC_TLB2CFG 32
PPC KVM_REG_PPC_TLB3CFG 32
PPC KVM_REG_PPC_TLB0PS 32
PPC KVM_REG_PPC_TLB1PS 32
PPC KVM_REG_PPC_TLB2PS 32
PPC KVM_REG_PPC_TLB3PS 32
PPC KVM_REG_PPC_EPTCFG 32
PPC KVM_REG_PPC_ICP_STATE 64
PPC KVM_REG_PPC_VP_STATE 128
PPC KVM_REG_PPC_TB_OFFSET 64
PPC KVM_REG_PPC_SPMC1 32
PPC KVM_REG_PPC_SPMC2 32
PPC KVM_REG_PPC_IAMR 64
PPC KVM_REG_PPC_TFHAR 64
PPC KVM_REG_PPC_TFIAR 64
PPC KVM_REG_PPC_TEXASR 64
PPC KVM_REG_PPC_FSCR 64
PPC KVM_REG_PPC_PSPB 32
PPC KVM_REG_PPC_EBBHR 64
PPC KVM_REG_PPC_EBBRR 64
PPC KVM_REG_PPC_BESCR 64
PPC KVM_REG_PPC_TAR 64
PPC KVM_REG_PPC_DPDES 64
PPC KVM_REG_PPC_DAWR 64
PPC KVM_REG_PPC_DAWRX 64
PPC KVM_REG_PPC_CIABR 64
PPC KVM_REG_PPC_IC 64
PPC KVM_REG_PPC_VTB 64
PPC KVM_REG_PPC_CSIGR 64
PPC KVM_REG_PPC_TACR 64
PPC KVM_REG_PPC_TCSCR 64
PPC KVM_REG_PPC_PID 64
PPC KVM_REG_PPC_ACOP 64
PPC KVM_REG_PPC_VRSAVE 32
PPC KVM_REG_PPC_LPCR 32
PPC KVM_REG_PPC_LPCR_64 64
PPC KVM_REG_PPC_PPR 64
PPC KVM_REG_PPC_ARCH_COMPAT 32
PPC KVM_REG_PPC_DABRX 32
PPC KVM_REG_PPC_WORT 64
PPC KVM_REG_PPC_SPRG9 64
PPC KVM_REG_PPC_DBSR 32
PPC KVM_REG_PPC_TIDR 64
PPC KVM_REG_PPC_PSSCR 64
PPC KVM_REG_PPC_DEC_EXPIRY 64
PPC KVM_REG_PPC_PTCR 64
PPC KVM_REG_PPC_HASHKEYR 64
PPC KVM_REG_PPC_HASHPKEYR 64
PPC KVM_REG_PPC_DAWR1 64
PPC KVM_REG_PPC_DAWRX1 64
PPC KVM_REG_PPC_DEXCR 64
PPC KVM_REG_PPC_TM_GPR0 64
...
PPC KVM_REG_PPC_TM_GPR31 64
PPC KVM_REG_PPC_TM_VSR0 128
...
PPC KVM_REG_PPC_TM_VSR63 128
PPC KVM_REG_PPC_TM_CR 64
PPC KVM_REG_PPC_TM_LR 64
PPC KVM_REG_PPC_TM_CTR 64
PPC KVM_REG_PPC_TM_FPSCR 64
PPC KVM_REG_PPC_TM_AMR 64
PPC KVM_REG_PPC_TM_PPR 64
PPC KVM_REG_PPC_TM_VRSAVE 64
PPC KVM_REG_PPC_TM_VSCR 32
PPC KVM_REG_PPC_TM_DSCR 64
PPC KVM_REG_PPC_TM_TAR 64
PPC KVM_REG_PPC_TM_XER 64
MIPS KVM_REG_MIPS_R0 64
...
MIPS KVM_REG_MIPS_R31 64
MIPS KVM_REG_MIPS_HI 64
MIPS KVM_REG_MIPS_LO 64
MIPS KVM_REG_MIPS_PC 64
MIPS KVM_REG_MIPS_CP0_INDEX 32
MIPS KVM_REG_MIPS_CP0_ENTRYLO0 64
MIPS KVM_REG_MIPS_CP0_ENTRYLO1 64
MIPS KVM_REG_MIPS_CP0_CONTEXT 64
MIPS KVM_REG_MIPS_CP0_CONTEXTCONFIG 32
MIPS KVM_REG_MIPS_CP0_USERLOCAL 64
MIPS KVM_REG_MIPS_CP0_XCONTEXTCONFIG 64
MIPS KVM_REG_MIPS_CP0_PAGEMASK 32
MIPS KVM_REG_MIPS_CP0_PAGEGRAIN 32
MIPS KVM_REG_MIPS_CP0_SEGCTL0 64
MIPS KVM_REG_MIPS_CP0_SEGCTL1 64
MIPS KVM_REG_MIPS_CP0_SEGCTL2 64
MIPS KVM_REG_MIPS_CP0_PWBASE 64
MIPS KVM_REG_MIPS_CP0_PWFIELD 64
MIPS KVM_REG_MIPS_CP0_PWSIZE 64
MIPS KVM_REG_MIPS_CP0_WIRED 32
MIPS KVM_REG_MIPS_CP0_PWCTL 32
MIPS KVM_REG_MIPS_CP0_HWRENA 32
MIPS KVM_REG_MIPS_CP0_BADVADDR 64
MIPS KVM_REG_MIPS_CP0_BADINSTR 32
MIPS KVM_REG_MIPS_CP0_BADINSTRP 32
MIPS KVM_REG_MIPS_CP0_COUNT 32
MIPS KVM_REG_MIPS_CP0_ENTRYHI 64
MIPS KVM_REG_MIPS_CP0_COMPARE 32
MIPS KVM_REG_MIPS_CP0_STATUS 32
MIPS KVM_REG_MIPS_CP0_INTCTL 32
MIPS KVM_REG_MIPS_CP0_CAUSE 32
MIPS KVM_REG_MIPS_CP0_EPC 64
MIPS KVM_REG_MIPS_CP0_PRID 32
MIPS KVM_REG_MIPS_CP0_EBASE 64
MIPS KVM_REG_MIPS_CP0_CONFIG 32
MIPS KVM_REG_MIPS_CP0_CONFIG1 32
MIPS KVM_REG_MIPS_CP0_CONFIG2 32
MIPS KVM_REG_MIPS_CP0_CONFIG3 32
MIPS KVM_REG_MIPS_CP0_CONFIG4 32
MIPS KVM_REG_MIPS_CP0_CONFIG5 32
MIPS KVM_REG_MIPS_CP0_CONFIG7 32
MIPS KVM_REG_MIPS_CP0_XCONTEXT 64
MIPS KVM_REG_MIPS_CP0_ERROREPC 64
MIPS KVM_REG_MIPS_CP0_KSCRATCH1 64
MIPS KVM_REG_MIPS_CP0_KSCRATCH2 64
MIPS KVM_REG_MIPS_CP0_KSCRATCH3 64
MIPS KVM_REG_MIPS_CP0_KSCRATCH4 64
MIPS KVM_REG_MIPS_CP0_KSCRATCH5 64
MIPS KVM_REG_MIPS_CP0_KSCRATCH6 64
MIPS KVM_REG_MIPS_CP0_MAAR(0..63) 64
MIPS KVM_REG_MIPS_COUNT_CTL 64
MIPS KVM_REG_MIPS_COUNT_RESUME 64
MIPS KVM_REG_MIPS_COUNT_HZ 64
MIPS KVM_REG_MIPS_FPR_32(0..31) 32
MIPS KVM_REG_MIPS_FPR_64(0..31) 64
MIPS KVM_REG_MIPS_VEC_128(0..31) 128
MIPS KVM_REG_MIPS_FCR_IR 32
MIPS KVM_REG_MIPS_FCR_CSR 32
MIPS KVM_REG_MIPS_MSA_IR 32
MIPS KVM_REG_MIPS_MSA_CSR 32
======= =============================== ============
ARM registers are mapped using the lower 32 bits. The upper 16 of that
is the register group type, or coprocessor number:
ARM core registers have the following id bit patterns::
0x4020 0000 0010 <index into the kvm_regs struct:16>
ARM 32-bit CP15 registers have the following id bit patterns::
0x4020 0000 000F <zero:1> <crn:4> <crm:4> <opc1:4> <opc2:3>
ARM 64-bit CP15 registers have the following id bit patterns::
0x4030 0000 000F <zero:1> <zero:4> <crm:4> <opc1:4> <zero:3>
ARM CCSIDR registers are demultiplexed by CSSELR value::
0x4020 0000 0011 00 <csselr:8>
ARM 32-bit VFP control registers have the following id bit patterns::
0x4020 0000 0012 1 <regno:12>
ARM 64-bit FP registers have the following id bit patterns::
0x4030 0000 0012 0 <regno:12>
ARM firmware pseudo-registers have the following bit pattern::
0x4030 0000 0014 <regno:16>
arm64 registers are mapped using the lower 32 bits. The upper 16 of
that is the register group type, or coprocessor number:
arm64 core/FP-SIMD registers have the following id bit patterns. Note
that the size of the access is variable, as the kvm_regs structure
contains elements ranging from 32 to 128 bits. The index is a 32bit
value in the kvm_regs structure seen as a 32bit array::
0x60x0 0000 0010 <index into the kvm_regs struct:16>
Specifically:
======================= ========= ===== =======================================
Encoding Register Bits kvm_regs member
======================= ========= ===== =======================================
0x6030 0000 0010 0000 X0 64 regs.regs[0]
0x6030 0000 0010 0002 X1 64 regs.regs[1]
...
0x6030 0000 0010 003c X30 64 regs.regs[30]
0x6030 0000 0010 003e SP 64 regs.sp
0x6030 0000 0010 0040 PC 64 regs.pc
0x6030 0000 0010 0042 PSTATE 64 regs.pstate
0x6030 0000 0010 0044 SP_EL1 64 sp_el1
0x6030 0000 0010 0046 ELR_EL1 64 elr_el1
0x6030 0000 0010 0048 SPSR_EL1 64 spsr[KVM_SPSR_EL1] (alias SPSR_SVC)
0x6030 0000 0010 004a SPSR_ABT 64 spsr[KVM_SPSR_ABT]
0x6030 0000 0010 004c SPSR_UND 64 spsr[KVM_SPSR_UND]
0x6030 0000 0010 004e SPSR_IRQ 64 spsr[KVM_SPSR_IRQ]
0x6030 0000 0010 0050 SPSR_FIQ 64 spsr[KVM_SPSR_FIQ]
0x6040 0000 0010 0054 V0 128 fp_regs.vregs[0] [1]_
0x6040 0000 0010 0058 V1 128 fp_regs.vregs[1] [1]_
...
0x6040 0000 0010 00d0 V31 128 fp_regs.vregs[31] [1]_
0x6020 0000 0010 00d4 FPSR 32 fp_regs.fpsr
0x6020 0000 0010 00d5 FPCR 32 fp_regs.fpcr
======================= ========= ===== =======================================
.. [1] These encodings are not accepted for SVE-enabled vcpus. See
:ref:`KVM_ARM_VCPU_INIT`.
The equivalent register content can be accessed via bits [127:0] of
the corresponding SVE Zn registers instead for vcpus that have SVE
enabled (see below).
arm64 CCSIDR registers are demultiplexed by CSSELR value::
0x6020 0000 0011 00 <csselr:8>
arm64 system registers have the following id bit patterns::
0x6030 0000 0013 <op0:2> <op1:3> <crn:4> <crm:4> <op2:3>
.. warning::
Two system register IDs do not follow the specified pattern. These
are KVM_REG_ARM_TIMER_CVAL and KVM_REG_ARM_TIMER_CNT, which map to
system registers CNTV_CVAL_EL0 and CNTVCT_EL0 respectively. These
two had their values accidentally swapped, which means TIMER_CVAL is
derived from the register encoding for CNTVCT_EL0 and TIMER_CNT is
derived from the register encoding for CNTV_CVAL_EL0. As this is
API, it must remain this way.
arm64 firmware pseudo-registers have the following bit pattern::
0x6030 0000 0014 <regno:16>
arm64 SVE registers have the following bit patterns::
0x6080 0000 0015 00 <n:5> <slice:5> Zn bits[2048*slice + 2047 : 2048*slice]
0x6050 0000 0015 04 <n:4> <slice:5> Pn bits[256*slice + 255 : 256*slice]
0x6050 0000 0015 060 <slice:5> FFR bits[256*slice + 255 : 256*slice]
0x6060 0000 0015 ffff KVM_REG_ARM64_SVE_VLS pseudo-register
Access to register IDs where 2048 * slice >= 128 * max_vq will fail with
ENOENT. max_vq is the vcpu's maximum supported vector length in 128-bit
quadwords: see [2]_ below.
These registers are only accessible on vcpus for which SVE is enabled.
See KVM_ARM_VCPU_INIT for details.
In addition, except for KVM_REG_ARM64_SVE_VLS, these registers are not
accessible until the vcpu's SVE configuration has been finalized
using KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE). See KVM_ARM_VCPU_INIT
and KVM_ARM_VCPU_FINALIZE for more information about this procedure.
KVM_REG_ARM64_SVE_VLS is a pseudo-register that allows the set of vector
lengths supported by the vcpu to be discovered and configured by
userspace. When transferred to or from user memory via KVM_GET_ONE_REG
or KVM_SET_ONE_REG, the value of this register is of type
__u64[KVM_ARM64_SVE_VLS_WORDS], and encodes the set of vector lengths as
follows::
__u64 vector_lengths[KVM_ARM64_SVE_VLS_WORDS];
if (vq >= SVE_VQ_MIN && vq <= SVE_VQ_MAX &&
((vector_lengths[(vq - KVM_ARM64_SVE_VQ_MIN) / 64] >>
((vq - KVM_ARM64_SVE_VQ_MIN) % 64)) & 1))
/* Vector length vq * 16 bytes supported */
else
/* Vector length vq * 16 bytes not supported */
.. [2] The maximum value vq for which the above condition is true is
max_vq. This is the maximum vector length available to the guest on
this vcpu, and determines which register slices are visible through
this ioctl interface.
(See Documentation/arch/arm64/sve.rst for an explanation of the "vq"
nomenclature.)
KVM_REG_ARM64_SVE_VLS is only accessible after KVM_ARM_VCPU_INIT.
KVM_ARM_VCPU_INIT initialises it to the best set of vector lengths that
the host supports.
Userspace may subsequently modify it if desired until the vcpu's SVE
configuration is finalized using KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE).
Apart from simply removing all vector lengths from the host set that
exceed some value, support for arbitrarily chosen sets of vector lengths
is hardware-dependent and may not be available. Attempting to configure
an invalid set of vector lengths via KVM_SET_ONE_REG will fail with
EINVAL.
After the vcpu's SVE configuration is finalized, further attempts to
write this register will fail with EPERM.
arm64 bitmap feature firmware pseudo-registers have the following bit pattern::
0x6030 0000 0016 <regno:16>
The bitmap feature firmware registers exposes the hypercall services that
are available for userspace to configure. The set bits corresponds to the
services that are available for the guests to access. By default, KVM
sets all the supported bits during VM initialization. The userspace can
discover the available services via KVM_GET_ONE_REG, and write back the
bitmap corresponding to the features that it wishes guests to see via
KVM_SET_ONE_REG.
Note: These registers are immutable once any of the vCPUs of the VM has
run at least once. A KVM_SET_ONE_REG in such a scenario will return
a -EBUSY to userspace.
(See Documentation/virt/kvm/arm/hypercalls.rst for more details.)
MIPS registers are mapped using the lower 32 bits. The upper 16 of that is
the register group type:
MIPS core registers (see above) have the following id bit patterns::
0x7030 0000 0000 <reg:16>
MIPS CP0 registers (see KVM_REG_MIPS_CP0_* above) have the following id bit
patterns depending on whether they're 32-bit or 64-bit registers::
0x7020 0000 0001 00 <reg:5> <sel:3> (32-bit)
0x7030 0000 0001 00 <reg:5> <sel:3> (64-bit)
Note: KVM_REG_MIPS_CP0_ENTRYLO0 and KVM_REG_MIPS_CP0_ENTRYLO1 are the MIPS64
versions of the EntryLo registers regardless of the word size of the host
hardware, host kernel, guest, and whether XPA is present in the guest, i.e.
with the RI and XI bits (if they exist) in bits 63 and 62 respectively, and
the PFNX field starting at bit 30.
MIPS MAARs (see KVM_REG_MIPS_CP0_MAAR(*) above) have the following id bit
patterns::
0x7030 0000 0001 01 <reg:8>
MIPS KVM control registers (see above) have the following id bit patterns::
0x7030 0000 0002 <reg:16>
MIPS FPU registers (see KVM_REG_MIPS_FPR_{32,64}() above) have the following
id bit patterns depending on the size of the register being accessed. They are
always accessed according to the current guest FPU mode (Status.FR and
Config5.FRE), i.e. as the guest would see them, and they become unpredictable
if the guest FPU mode is changed. MIPS SIMD Architecture (MSA) vector
registers (see KVM_REG_MIPS_VEC_128() above) have similar patterns as they
overlap the FPU registers::
0x7020 0000 0003 00 <0:3> <reg:5> (32-bit FPU registers)
0x7030 0000 0003 00 <0:3> <reg:5> (64-bit FPU registers)
0x7040 0000 0003 00 <0:3> <reg:5> (128-bit MSA vector registers)
MIPS FPU control registers (see KVM_REG_MIPS_FCR_{IR,CSR} above) have the
following id bit patterns::
0x7020 0000 0003 01 <0:3> <reg:5>
MIPS MSA control registers (see KVM_REG_MIPS_MSA_{IR,CSR} above) have the
following id bit patterns::
0x7020 0000 0003 02 <0:3> <reg:5>
RISC-V registers are mapped using the lower 32 bits. The upper 8 bits of
that is the register group type.
RISC-V config registers are meant for configuring a Guest VCPU and it has
the following id bit patterns::
0x8020 0000 01 <index into the kvm_riscv_config struct:24> (32bit Host)
0x8030 0000 01 <index into the kvm_riscv_config struct:24> (64bit Host)
Following are the RISC-V config registers:
======================= ========= =============================================
Encoding Register Description
======================= ========= =============================================
0x80x0 0000 0100 0000 isa ISA feature bitmap of Guest VCPU
======================= ========= =============================================
The isa config register can be read anytime but can only be written before
a Guest VCPU runs. It will have ISA feature bits matching underlying host
set by default.
RISC-V core registers represent the general execution state of a Guest VCPU
and it has the following id bit patterns::
0x8020 0000 02 <index into the kvm_riscv_core struct:24> (32bit Host)
0x8030 0000 02 <index into the kvm_riscv_core struct:24> (64bit Host)
Following are the RISC-V core registers:
======================= ========= =============================================
Encoding Register Description
======================= ========= =============================================
0x80x0 0000 0200 0000 regs.pc Program counter
0x80x0 0000 0200 0001 regs.ra Return address
0x80x0 0000 0200 0002 regs.sp Stack pointer
0x80x0 0000 0200 0003 regs.gp Global pointer
0x80x0 0000 0200 0004 regs.tp Task pointer
0x80x0 0000 0200 0005 regs.t0 Caller saved register 0
0x80x0 0000 0200 0006 regs.t1 Caller saved register 1
0x80x0 0000 0200 0007 regs.t2 Caller saved register 2
0x80x0 0000 0200 0008 regs.s0 Callee saved register 0
0x80x0 0000 0200 0009 regs.s1 Callee saved register 1
0x80x0 0000 0200 000a regs.a0 Function argument (or return value) 0
0x80x0 0000 0200 000b regs.a1 Function argument (or return value) 1
0x80x0 0000 0200 000c regs.a2 Function argument 2
0x80x0 0000 0200 000d regs.a3 Function argument 3
0x80x0 0000 0200 000e regs.a4 Function argument 4
0x80x0 0000 0200 000f regs.a5 Function argument 5
0x80x0 0000 0200 0010 regs.a6 Function argument 6
0x80x0 0000 0200 0011 regs.a7 Function argument 7
0x80x0 0000 0200 0012 regs.s2 Callee saved register 2
0x80x0 0000 0200 0013 regs.s3 Callee saved register 3
0x80x0 0000 0200 0014 regs.s4 Callee saved register 4
0x80x0 0000 0200 0015 regs.s5 Callee saved register 5
0x80x0 0000 0200 0016 regs.s6 Callee saved register 6
0x80x0 0000 0200 0017 regs.s7 Callee saved register 7
0x80x0 0000 0200 0018 regs.s8 Callee saved register 8
0x80x0 0000 0200 0019 regs.s9 Callee saved register 9
0x80x0 0000 0200 001a regs.s10 Callee saved register 10
0x80x0 0000 0200 001b regs.s11 Callee saved register 11
0x80x0 0000 0200 001c regs.t3 Caller saved register 3
0x80x0 0000 0200 001d regs.t4 Caller saved register 4
0x80x0 0000 0200 001e regs.t5 Caller saved register 5
0x80x0 0000 0200 001f regs.t6 Caller saved register 6
0x80x0 0000 0200 0020 mode Privilege mode (1 = S-mode or 0 = U-mode)
======================= ========= =============================================
RISC-V csr registers represent the supervisor mode control/status registers
of a Guest VCPU and it has the following id bit patterns::
0x8020 0000 03 <index into the kvm_riscv_csr struct:24> (32bit Host)
0x8030 0000 03 <index into the kvm_riscv_csr struct:24> (64bit Host)
Following are the RISC-V csr registers:
======================= ========= =============================================
Encoding Register Description
======================= ========= =============================================
0x80x0 0000 0300 0000 sstatus Supervisor status
0x80x0 0000 0300 0001 sie Supervisor interrupt enable
0x80x0 0000 0300 0002 stvec Supervisor trap vector base
0x80x0 0000 0300 0003 sscratch Supervisor scratch register
0x80x0 0000 0300 0004 sepc Supervisor exception program counter
0x80x0 0000 0300 0005 scause Supervisor trap cause
0x80x0 0000 0300 0006 stval Supervisor bad address or instruction
0x80x0 0000 0300 0007 sip Supervisor interrupt pending
0x80x0 0000 0300 0008 satp Supervisor address translation and protection
======================= ========= =============================================
RISC-V timer registers represent the timer state of a Guest VCPU and it has
the following id bit patterns::
0x8030 0000 04 <index into the kvm_riscv_timer struct:24>
Following are the RISC-V timer registers:
======================= ========= =============================================
Encoding Register Description
======================= ========= =============================================
0x8030 0000 0400 0000 frequency Time base frequency (read-only)
0x8030 0000 0400 0001 time Time value visible to Guest
0x8030 0000 0400 0002 compare Time compare programmed by Guest
0x8030 0000 0400 0003 state Time compare state (1 = ON or 0 = OFF)
======================= ========= =============================================
RISC-V F-extension registers represent the single precision floating point
state of a Guest VCPU and it has the following id bit patterns::
0x8020 0000 05 <index into the __riscv_f_ext_state struct:24>
Following are the RISC-V F-extension registers:
======================= ========= =============================================
Encoding Register Description
======================= ========= =============================================
0x8020 0000 0500 0000 f[0] Floating point register 0
...
0x8020 0000 0500 001f f[31] Floating point register 31
0x8020 0000 0500 0020 fcsr Floating point control and status register
======================= ========= =============================================
RISC-V D-extension registers represent the double precision floating point
state of a Guest VCPU and it has the following id bit patterns::
0x8020 0000 06 <index into the __riscv_d_ext_state struct:24> (fcsr)
0x8030 0000 06 <index into the __riscv_d_ext_state struct:24> (non-fcsr)
Following are the RISC-V D-extension registers:
======================= ========= =============================================
Encoding Register Description
======================= ========= =============================================
0x8030 0000 0600 0000 f[0] Floating point register 0
...
0x8030 0000 0600 001f f[31] Floating point register 31
0x8020 0000 0600 0020 fcsr Floating point control and status register
======================= ========= =============================================
LoongArch registers are mapped using the lower 32 bits. The upper 16 bits of
that is the register group type.
LoongArch csr registers are used to control guest cpu or get status of guest
cpu, and they have the following id bit patterns::
0x9030 0000 0001 00 <reg:5> <sel:3> (64-bit)
LoongArch KVM control registers are used to implement some new defined functions
such as set vcpu counter or reset vcpu, and they have the following id bit patterns::
0x9030 0000 0002 <reg:16>
x86 MSR registers have the following id bit patterns::
0x2030 0002 <msr number:32>
Following are the KVM-defined registers for x86:
======================= ========= =============================================
Encoding Register Description
======================= ========= =============================================
0x2030 0003 0000 0000 SSP Shadow Stack Pointer
======================= ========= =============================================
4.69 KVM_GET_ONE_REG
2927-2956`KVM_GET_ONE_REG`는 모든 architecture의 `KVM_CAP_ONE_REG` vCPU ioctl입니다. 입력 `struct kvm_one_reg`의 `id`가 읽을 register를 지정하고, 성공하면 `addr`가 가리키는 userspace memory에 register 값이 기록됩니다.
errno대표 의미
`ENOENT`해당 register가 없음
`EINVAL`잘못된 ID·미지원 register 또는 s390 protected virtualization VM
`EPERM`arm64 vCPU finalize 전에 허용되지 않는 register 접근
이 errno 역시 지표일 뿐 특정 상황에서 정확히 어느 값이 반환될지 의존하면 안 됩니다.
읽을 수 있는 register 목록은 4.68 `KVM_SET_ONE_REG`에서 설명한 목록과 동일합니다. 따라서 architecture별 ID encoding, register width, SVE finalize 규칙도 그대로 적용됩니다.
4.69 KVM_GET_ONE_REG
--------------------
:Capability: KVM_CAP_ONE_REG
:Architectures: all
:Type: vcpu ioctl
:Parameters: struct kvm_one_reg (in and out)
:Returns: 0 on success, negative value on failure
Errors include:
======== ============================================================
ENOENT no such register
EINVAL invalid register ID, or no such register or used with VMs in
protected virtualization mode on s390
EPERM (arm64) register access not allowed before vcpu finalization
======== ============================================================
(These error codes are indicative only: do not rely on a specific error
code being returned in a specific situation.)
This ioctl allows to receive the value of a single register implemented
in a vcpu. The register to read is indicated by the "id" field of the
kvm_one_reg struct passed in. On success, the register value can be found
at the memory location pointed to by "addr".
The list of registers accessible using this interface is identical to the
list in 4.68.
4.70 KVM_KVMCLOCK_CTRL
2957-2980`KVM_KVMCLOCK_CTRL`은 paravirtual clock을 구현하는 architecture에서 사용하는 `KVM_CAP_KVMCLOCK_CTRL` vCPU ioctl이며 현재는 x86만 해당합니다. Argument 없이 성공 시 0을 반환합니다.
호스트 userspace가 해당 vCPU를 일시 정지했다는 사실을 guest에 알리는 flag를 설정합니다. 이 flag는 host와 guest가 공유하는 `pvclock_vcpu_time_info.flags`의 두 번째 bit이며 soft-lockup watchdog이 검사합니다.
Host만 flag를 set하고 guest만 읽고 clear합니다. Guest의 검사·clear는 load-link/store-conditional 또는 동등한 방법으로 atomic해야 합니다. Guest는 watchdog timer가 스스로 reset되거나 soft lockup을 감지했을 때 flag를 clear합니다.
이 ioctl은 vCPU를 pause한 뒤 resume하기 전 사이에 언제든 호출할 수 있습니다.
4.70 KVM_KVMCLOCK_CTRL
----------------------
:Capability: KVM_CAP_KVMCLOCK_CTRL
:Architectures: Any that implement pvclocks (currently x86 only)
:Type: vcpu ioctl
:Parameters: None
:Returns: 0 on success, -1 on error
This ioctl sets a flag accessible to the guest indicating that the specified
vCPU has been paused by the host userspace.
The host will set a flag in the pvclock structure that is checked from the
soft lockup watchdog. The flag is part of the pvclock structure that is
shared between guest and host, specifically the second bit of the flags
field of the pvclock_vcpu_time_info structure. It will be set exclusively by
the host and read/cleared exclusively by the guest. The guest operation of
checking and clearing the flag must be an atomic operation so
load-link/store-conditional, or equivalent must be used. There are two cases
where the guest will clear the flag: when the soft lockup watchdog timer resets
itself or when a soft lockup is detected. This ioctl can be called any time
after pausing the vcpu, but before it is resumed.
4.71 KVM_SIGNAL_MSI
2981-3019`KVM_SIGNAL_MSI`는 x86·arm64의 `KVM_CAP_SIGNAL_MSI` VM ioctl이며 kernel 내부 irqchip이 MSI message를 처리할 때만 유효합니다. MSI를 직접 주입하고 전달되면 양수, guest가 MSI를 block하면 0, 오류면 -1을 반환합니다.
Field의미
`address_lo`, `address_hi`MSI destination address
`data`MSI payload
`flags`현재 `KVM_MSI_VALID_DEVID` 사용
`devid`MSI를 기록한 device의 고유 identifier
`pad[12]`예약 영역
MSI address·data와 선택적 device identifier를 전달합니다.
`KVM_MSI_VALID_DEVID`를 set하면 `devid`가 유효합니다. VM별 `KVM_CAP_MSI_DEVID`가 device ID 제공 요구를 알리며, 이 capability가 없으면 userspace는 ioctl 실패 가능성이 있으므로 해당 flag를 set하면 안 됩니다.
PCI device의 `devid`는 보통 하위 16 bit에 BDF identifier를 담습니다.
x86에서는 `KVM_CAP_X2APIC_API`의 `KVM_X2APIC_API_USE_32BIT_IDS`가 enable되지 않으면 `address_hi`를 무시합니다. Enable된 경우 `address_hi[31:8]`은 destination ID의 bit 31:8이고 bit 7:0은 반드시 0이어야 합니다.
4.71 KVM_SIGNAL_MSI
-------------------
:Capability: KVM_CAP_SIGNAL_MSI
:Architectures: x86 arm64
:Type: vm ioctl
:Parameters: struct kvm_msi (in)
:Returns: >0 on delivery, 0 if guest blocked the MSI, and -1 on error
Directly inject a MSI message. Only valid with in-kernel irqchip that handles
MSI messages.
::
struct kvm_msi {
__u32 address_lo;
__u32 address_hi;
__u32 data;
__u32 flags;
__u32 devid;
__u8 pad[12];
};
flags:
KVM_MSI_VALID_DEVID: devid contains a valid value. The per-VM
KVM_CAP_MSI_DEVID capability advertises the requirement to provide
the device ID. If this capability is not available, userspace
should never set the KVM_MSI_VALID_DEVID flag as the ioctl might fail.
If KVM_MSI_VALID_DEVID is set, devid contains a unique device identifier
for the device that wrote the MSI message. For PCI, this is usually a
BDF identifier in the lower 16 bits.
On x86, address_hi is ignored unless the KVM_X2APIC_API_USE_32BIT_IDS
feature of KVM_CAP_X2APIC_API capability is enabled. If it is enabled,
address_hi bits 31-8 provide bits 31-8 of the destination id. Bits 7-0 of
address_hi must be zero.
4.71 KVM_CREATE_PIT2
3020-3052`KVM_CREATE_PIT2`는 x86 `KVM_CAP_PIT2` VM ioctl로 kernel 내부 i8254 PIT device model을 만듭니다. 먼저 `KVM_CREATE_IRQCHIP`으로 kernel irqchip support를 enable한 뒤에만 호출할 수 있습니다.
입력 `struct kvm_pit_config`는 `flags`와 예약된 `pad[15]`를 담습니다. `KVM_PIT_SPEAKER_DUMMY` flag 값 1은 speaker port stub을 emulate합니다.
PIT timer interrupt 주입에는 VM별 kernel thread가 사용될 수 있으며 이름은 `kvm-pit/<owner-process-pid>` 형식입니다. Guest를 높은 priority로 실행한다면 이 thread의 scheduling parameter도 그에 맞춰 조정해야 할 수 있습니다.
이 ioctl은 obsolete `KVM_CREATE_PIT`을 대체합니다.
4.71 KVM_CREATE_PIT2
--------------------
:Capability: KVM_CAP_PIT2
:Architectures: x86
:Type: vm ioctl
:Parameters: struct kvm_pit_config (in)
:Returns: 0 on success, -1 on error
Creates an in-kernel device model for the i8254 PIT. This call is only valid
after enabling in-kernel irqchip support via KVM_CREATE_IRQCHIP. The following
parameters have to be passed::
struct kvm_pit_config {
__u32 flags;
__u32 pad[15];
};
Valid flags are::
#define KVM_PIT_SPEAKER_DUMMY 1 /* emulate speaker port stub */
PIT timer interrupts may use a per-VM kernel thread for injection. If it
exists, this thread will have a name of the following pattern::
kvm-pit/<owner-process-pid>
When running a guest with elevated priorities, the scheduling parameters of
this thread may have to be adjusted accordingly.
This IOCTL replaces the obsolete KVM_CREATE_PIT.
4.72 KVM_GET_PIT2
3053-3080`KVM_GET_PIT2`는 x86 `KVM_CAP_PIT_STATE2` VM ioctl이며 `KVM_CREATE_PIT2` 뒤에 kernel 내부 PIT model의 상태를 `struct kvm_pit_state2`로 가져옵니다.
구조체에는 `kvm_pit_channel_state channels[3]`, `flags`, 예약된 `reserved[9]`가 들어 있습니다.
Flag의미
`KVM_PIT_FLAGS_HPET_LEGACY`HPET legacy mode에서 PIT disable
`KVM_PIT_FLAGS_SPEAKER_DATA_ON`Speaker port data bit enable
PIT와 HPET legacy mode 및 speaker 상태를 나타냅니다.
이 ioctl은 obsolete `KVM_GET_PIT`을 대체합니다.
4.72 KVM_GET_PIT2
-----------------
:Capability: KVM_CAP_PIT_STATE2
:Architectures: x86
:Type: vm ioctl
:Parameters: struct kvm_pit_state2 (out)
:Returns: 0 on success, -1 on error
Retrieves the state of the in-kernel PIT model. Only valid after
KVM_CREATE_PIT2. The state is returned in the following structure::
struct kvm_pit_state2 {
struct kvm_pit_channel_state channels[3];
__u32 flags;
__u32 reserved[9];
};
Valid flags are::
/* disable PIT in HPET legacy mode */
#define KVM_PIT_FLAGS_HPET_LEGACY 0x00000001
/* speaker port data bit enabled */
#define KVM_PIT_FLAGS_SPEAKER_DATA_ON 0x00000002
This IOCTL replaces the obsolete KVM_GET_PIT.
4.73 KVM_SET_PIT2
3081-3101`KVM_SET_PIT2`는 x86 `KVM_CAP_PIT_STATE2` VM ioctl이며 `KVM_CREATE_PIT2` 뒤에 `struct kvm_pit_state2`로 kernel 내부 PIT model 상태를 설정합니다. 구조체 세부 사항은 `KVM_GET_PIT2`와 같습니다.
이 호출은 Intel 8254 PIT specification을 엄격히 따릅니다. 예를 들어 `struct kvm_pit_channel_state.count`가 0이면 최대 count인 65,536으로 해석합니다.
이 ioctl은 obsolete `KVM_SET_PIT`을 대체합니다.
4.73 KVM_SET_PIT2
-----------------
:Capability: KVM_CAP_PIT_STATE2
:Architectures: x86
:Type: vm ioctl
:Parameters: struct kvm_pit_state2 (in)
:Returns: 0 on success, -1 on error
Sets the state of the in-kernel PIT model. Only valid after KVM_CREATE_PIT2.
See KVM_GET_PIT2 for details on struct kvm_pit_state2.
.. Tip::
``KVM_SET_PIT2`` strictly adheres to the spec of Intel 8254 PIT. For example,
a ``count`` value of 0 in ``struct kvm_pit_channel_state`` is interpreted as
65536, which is the maximum count value. Refer to `Intel 8254 programmable
interval timer <https://www.scs.stanford.edu/10wi-cs140/pintos/specs/8254.pdf>`_.
This IOCTL replaces the obsolete KVM_SET_PIT.
4.74 KVM_PPC_GET_SMMU_INFO
3102-3176`KVM_PPC_GET_SMMU_INFO`는 PowerPC `KVM_CAP_PPC_GET_SMMU_INFO` VM ioctl입니다. KVM이 지원하는 Server-class MMU emulation feature를 `struct kvm_ppc_smmu_info`에 채워 반환하며, userspace는 이 정보로 guest OS용 device-tree property를 만들 수 있습니다.
`kvm_ppc_smmu_info`는 global `flags`, 지원 SLB entry 수인 `slb_size`, padding, 그리고 지원 segment page size 배열 `sps[KVM_PPC_PAGE_SIZES_MAX_SZ]`를 담습니다.
Flag의미
`KVM_PPC_PAGE_SIZES_REAL`Guest page size가 backing-store page size에 맞아야 함
`KVM_PPC_1T_SEGMENTS`표준 256MiB segment 외에 1TiB segment 지원
`KVM_PPC_NO_HASH`HPT guest 미지원, 모든 guest가 radix MMU mode를 사용해야 함
Guest MMU mode와 page-size 제약을 설명합니다.
`sps` 배열에는 segment가 지원하는 base page size를 오름차순으로 최대 8개 기록합니다. `kvm_ppc_one_seg_page_size.page_shift`가 0이면 사용하지 않는 entry이며 정렬 특성상 그 지점에서 검색을 끝낼 수 있습니다.
각 segment entry의 `slb_enc`는 BookS SLB encoding입니다. Bit 위치가 맞춰져 있어 `slbmte` instruction의 `vsid` argument에 직접 OR할 수 있습니다.
`enc` 배열은 해당 segment base page size에서 지원하는 실제 page size와 hash PTE encoding을 오름차순으로 나열합니다. 실제 page size는 base page size보다 크거나 같아야 하고 shift 0 entry가 빈 entry이자 terminator입니다.
`kvm_ppc_one_page_size.pte_enc`는 hash PTE의 RPN field에 넣을 값입니다. Hash PTE 두 번째 doubleword에 OR하기 전에 12 bit 왼쪽으로 shift해야 합니다.
4.74 KVM_PPC_GET_SMMU_INFO
--------------------------
:Capability: KVM_CAP_PPC_GET_SMMU_INFO
:Architectures: powerpc
:Type: vm ioctl
:Parameters: None
:Returns: 0 on success, -1 on error
This populates and returns a structure describing the features of
the "Server" class MMU emulation supported by KVM.
This can in turn be used by userspace to generate the appropriate
device-tree properties for the guest operating system.
The structure contains some global information, followed by an
array of supported segment page sizes::
struct kvm_ppc_smmu_info {
__u64 flags;
__u32 slb_size;
__u32 pad;
struct kvm_ppc_one_seg_page_size sps[KVM_PPC_PAGE_SIZES_MAX_SZ];
};
The supported flags are:
- KVM_PPC_PAGE_SIZES_REAL:
When that flag is set, guest page sizes must "fit" the backing
store page sizes. When not set, any page size in the list can
be used regardless of how they are backed by userspace.
- KVM_PPC_1T_SEGMENTS
The emulated MMU supports 1T segments in addition to the
standard 256M ones.
- KVM_PPC_NO_HASH
This flag indicates that HPT guests are not supported by KVM,
thus all guests must use radix MMU mode.
The "slb_size" field indicates how many SLB entries are supported
The "sps" array contains 8 entries indicating the supported base
page sizes for a segment in increasing order. Each entry is defined
as follow::
struct kvm_ppc_one_seg_page_size {
__u32 page_shift; /* Base page shift of segment (or 0) */
__u32 slb_enc; /* SLB encoding for BookS */
struct kvm_ppc_one_page_size enc[KVM_PPC_PAGE_SIZES_MAX_SZ];
};
An entry with a "page_shift" of 0 is unused. Because the array is
organized in increasing order, a lookup can stop when encountering
such an entry.
The "slb_enc" field provides the encoding to use in the SLB for the
page size. The bits are in positions such as the value can directly
be OR'ed into the "vsid" argument of the slbmte instruction.
The "enc" array is a list which for each of those segment base page
size provides the list of supported actual page sizes (which can be
only larger or equal to the base page size), along with the
corresponding encoding in the hash PTE. Similarly, the array is
8 entries sorted by increasing sizes and an entry with a "0" shift
is an empty entry and a terminator::
struct kvm_ppc_one_page_size {
__u32 page_shift; /* Page shift (or 0) */
__u32 pte_enc; /* Encoding in the HPTE (>>12) */
};
The "pte_enc" field provides a value that can OR'ed into the hash
PTE's RPN field (ie, it needs to be shifted left by 12 to OR it
into the hash PTE second double word).
4.75 KVM_IRQFD
3177-3215`KVM_IRQFD`는 x86·s390·arm64의 `KVM_CAP_IRQFD` VM ioctl입니다. `kvm_irqfd.fd`의 eventfd에 event가 발생하면 `kvm_irqfd.gsi`가 지정한 irqchip pin으로 guest interrupt를 직접 주입합니다.
IRQFD를 제거할 때는 `KVM_IRQFD_FLAG_DEASSIGN`을 set하고 등록 때 사용한 `fd`와 `gsi`를 함께 지정합니다.
`KVM_CAP_IRQFD_RESAMPLE`이 있으면 level-triggered interrupt의 deassert·notification을 지원합니다. 등록 시 `KVM_IRQFD_FLAG_RESAMPLE`을 set하고 `resamplefd`를 제공하면 irqfd event가 GSI를 assert하고 EOI 같은 irqchip resample 때 GSI가 deassert되며 userspace가 `resamplefd`로 알림을 받습니다.
장치가 여전히 service를 요구하면 userspace가 interrupt를 다시 queue해야 합니다. `resamplefd`를 닫는 것만으로 irqfd가 disable되지는 않으며, `KVM_IRQFD_FLAG_RESAMPLE`은 등록 때만 필요하고 deassign 때는 생략할 수 있습니다.
Routing 상태결과
Entry 없음Interrupt 주입 실패
irqchip routing`irqchip.pin + 32`가 주입되는 SPI ID
MSI routingMSI message와 device ID를 LPI로 변환; kernel GICv3 ITS emulation만 지원
arm64에서 GSI에 연결된 routing entry에 따라 주입 결과가 달라집니다.
4.75 KVM_IRQFD
--------------
:Capability: KVM_CAP_IRQFD
:Architectures: x86 s390 arm64
:Type: vm ioctl
:Parameters: struct kvm_irqfd (in)
:Returns: 0 on success, -1 on error
Allows setting an eventfd to directly trigger a guest interrupt.
kvm_irqfd.fd specifies the file descriptor to use as the eventfd and
kvm_irqfd.gsi specifies the irqchip pin toggled by this event. When
an event is triggered on the eventfd, an interrupt is injected into
the guest using the specified gsi pin. The irqfd is removed using
the KVM_IRQFD_FLAG_DEASSIGN flag, specifying both kvm_irqfd.fd
and kvm_irqfd.gsi.
With KVM_CAP_IRQFD_RESAMPLE, KVM_IRQFD supports a de-assert and notify
mechanism allowing emulation of level-triggered, irqfd-based
interrupts. When KVM_IRQFD_FLAG_RESAMPLE is set the user must pass an
additional eventfd in the kvm_irqfd.resamplefd field. When operating
in resample mode, posting of an interrupt through kvm_irq.fd asserts
the specified gsi in the irqchip. When the irqchip is resampled, such
as from an EOI, the gsi is de-asserted and the user is notified via
kvm_irqfd.resamplefd. It is the user's responsibility to re-queue
the interrupt if the device making use of it still requires service.
Note that closing the resamplefd is not sufficient to disable the
irqfd. The KVM_IRQFD_FLAG_RESAMPLE is only necessary on assignment
and need not be specified with KVM_IRQFD_FLAG_DEASSIGN.
On arm64, gsi routing being supported, the following can happen:
- in case no routing entry is associated to this gsi, injection fails
- in case the gsi is associated to an irqchip routing entry,
irqchip.pin + 32 corresponds to the injected SPI ID.
- in case the gsi is associated to an MSI routing entry, the MSI
message and device ID are translated into an LPI (support restricted
to GICv3 ITS in-kernel emulation).
4.76 KVM_PPC_ALLOCATE_HTAB
3216-3252`KVM_PPC_ALLOCATE_HTAB`은 PowerPC `KVM_CAP_PPC_ALLOC_HTAB` VM ioctl로 PAPR paravirtualization guest의 MMU hash table을 host kernel에 할당하도록 요청합니다. Book 3S HV virtualization에서만 동작하며 그 외에는 capability가 없고 `ENOTTY`를 반환합니다.
호출 중 실행 중인 vCPU가 하나라도 있으면 아무 작업도 하지 않고 `EBUSY`를 반환합니다.
Argument는 원하는 hash-table size의 base-2 order를 담은 32-bit unsigned integer pointer이며 order는 18~46이어야 합니다. 성공해도 kernel은 이 입력값을 바꾸지 않습니다.
첫 `KVM_RUN` 시점까지 hash table을 할당하지 않았다면 host kernel이 기본 크기 16MiB table을 할당합니다.
기존 table과 다른 order를 요청하면 기존 table을 free하고 새로 할당합니다. 같은 order면 기존 table의 모든 HPTE를 0으로 clear합니다. 어느 경우든 guest가 VRMA facility를 사용하면 다음 vCPU `KVM_RUN`에서 VRMA HPTE를 다시 만듭니다.
4.76 KVM_PPC_ALLOCATE_HTAB
--------------------------
:Capability: KVM_CAP_PPC_ALLOC_HTAB
:Architectures: powerpc
:Type: vm ioctl
:Parameters: Pointer to u32 containing hash table order (in/out)
:Returns: 0 on success, -1 on error
This requests the host kernel to allocate an MMU hash table for a
guest using the PAPR paravirtualization interface. This only does
anything if the kernel is configured to use the Book 3S HV style of
virtualization. Otherwise the capability doesn't exist and the ioctl
returns an ENOTTY error. The rest of this description assumes Book 3S
HV.
There must be no vcpus running when this ioctl is called; if there
are, it will do nothing and return an EBUSY error.
The parameter is a pointer to a 32-bit unsigned integer variable
containing the order (log base 2) of the desired size of the hash
table, which must be between 18 and 46. On successful return from the
ioctl, the value will not be changed by the kernel.
If no hash table has been allocated when any vcpu is asked to run
(with the KVM_RUN ioctl), the host kernel will allocate a
default-sized hash table (16 MB).
If this ioctl is called when a hash table has already been allocated,
with a different order from the existing hash table, the existing hash
table will be freed and a new one allocated. If this is ioctl is
called when a hash table has already been allocated of the same order
as specified, the kernel will clear out the existing hash table (zero
all HPTEs). In either case, if the guest is using the virtualized
real-mode area (VRMA) facility, the kernel will re-create the VMRA
HPTEs on the next KVM_RUN of any vcpu.
4.77 KVM_S390_INTERRUPT
3253-3307`KVM_S390_INTERRUPT`는 s390 VM 또는 vCPU ioctl로 guest에 interrupt를 주입합니다. Interrupt type에 따라 VM ioctl의 floating interrupt 또는 vCPU별 interrupt가 됩니다.
입력 `struct kvm_s390_interrupt`는 32-bit `type`, 32-bit `parm`, 64-bit `parm64`를 담습니다.
Type범위·내용
`KVM_S390_SIGP_STOP`vCPU; SIGP stop, `parm`에 선택적 flag
`KVM_S390_PROGRAM_INT`vCPU; program check, `parm`에 code
`KVM_S390_SIGP_SET_PREFIX`vCPU; SIGP set-prefix, `parm`에 prefix address
`KVM_S390_RESTART`vCPU; restart
`KVM_S390_INT_CLOCK_COMP`vCPU; clock-comparator interrupt
`KVM_S390_INT_CPU_TIMER`vCPU; CPU-timer interrupt
`KVM_S390_INT_VIRTIO`VM; virtio external interrupt, `parm`·`parm64`에 parameter
`KVM_S390_INT_SERVICE`VM; SCLP external interrupt, `parm`에 SCLP parameter
`KVM_S390_INT_EMERGENCY`vCPU; SIGP emergency, `parm`에 source CPU
`KVM_S390_INT_EXTERNAL_CALL`vCPU; SIGP external call, `parm`에 source CPU
`KVM_S390_INT_IO`VM; adapter·subchannel 복합 값, `parm`·`parm64`에 I/O interruption 정보
`KVM_S390_MCHK`VM 또는 vCPU; `parm`에 CR14 bit, `parm64`에 machine-check code
각 type의 호출 범위와 parameter 의미입니다.
추가 payload가 필요한 machine check는 이 ioctl로 지원하지 않습니다. 이 호출은 asynchronous vCPU ioctl이므로 어떤 thread에서도 실행할 수 있습니다.
4.77 KVM_S390_INTERRUPT
-----------------------
:Capability: basic
:Architectures: s390
:Type: vm ioctl, vcpu ioctl
:Parameters: struct kvm_s390_interrupt (in)
:Returns: 0 on success, -1 on error
Allows to inject an interrupt to the guest. Interrupts can be floating
(vm ioctl) or per cpu (vcpu ioctl), depending on the interrupt type.
Interrupt parameters are passed via kvm_s390_interrupt::
struct kvm_s390_interrupt {
__u32 type;
__u32 parm;
__u64 parm64;
};
type can be one of the following:
KVM_S390_SIGP_STOP (vcpu)
- sigp stop; optional flags in parm
KVM_S390_PROGRAM_INT (vcpu)
- program check; code in parm
KVM_S390_SIGP_SET_PREFIX (vcpu)
- sigp set prefix; prefix address in parm
KVM_S390_RESTART (vcpu)
- restart
KVM_S390_INT_CLOCK_COMP (vcpu)
- clock comparator interrupt
KVM_S390_INT_CPU_TIMER (vcpu)
- CPU timer interrupt
KVM_S390_INT_VIRTIO (vm)
- virtio external interrupt; external interrupt
parameters in parm and parm64
KVM_S390_INT_SERVICE (vm)
- sclp external interrupt; sclp parameter in parm
KVM_S390_INT_EMERGENCY (vcpu)
- sigp emergency; source cpu in parm
KVM_S390_INT_EXTERNAL_CALL (vcpu)
- sigp external call; source cpu in parm
KVM_S390_INT_IO(ai,cssid,ssid,schid) (vm)
- compound value to indicate an
I/O interrupt (ai - adapter interrupt; cssid,ssid,schid - subchannel);
I/O interruption parameters in parm (subchannel) and parm64 (intparm,
interruption subclass)
KVM_S390_MCHK (vm, vcpu)
- machine check interrupt; cr 14 bits in parm, machine check interrupt
code in parm64 (note that machine checks needing further payload are not
supported by this ioctl)
This is an asynchronous vcpu ioctl and can be invoked from any thread.
4.78 KVM_PPC_GET_HTAB_FD
3308-3362`KVM_PPC_GET_HTAB_FD`는 PowerPC `KVM_CAP_PPC_HTAB_FD` VM ioctl이며 guest hashed page table(HPT)을 읽거나 초기화 entry를 쓰는 file descriptor를 반환합니다.
`struct kvm_get_htab_fd.flags`에 `KVM_GET_HTAB_WRITE`를 set한 fd는 write 전용이고, clear한 fd는 read 전용입니다. `start_index`는 읽기를 시작할 HPT index이며 쓰기에서는 무시됩니다. `reserved[2]`는 예약 영역입니다.
Flag의미
`KVM_GET_HTAB_BOLTED_ONLY`Bolted bit가 set된 HPT entry만 interesting entry로 취급
`KVM_GET_HTAB_WRITE`반환 fd를 HPT 초기화 write 용도로 생성
읽기 범위와 fd 방향을 고릅니다.
Read는 처음에 모든 interesting HPT entry 정보를 제공합니다. HPT 끝에 도달하면 `read()`가 반환되고, 같은 fd에서 다시 읽으면 HPT 처음부터 시작하되 직전 read 이후 변경된 entry만 반환합니다.
Stream은 8-byte `struct kvm_get_htab_header` 뒤에 유효한 HPT entry가 각각 16 byte씩 이어집니다. Header의 `index`는 시작 위치, `n_valid`는 이어지는 유효 entry 수, `n_invalid`는 그 뒤의 무효 entry 수입니다. 무효 entry 자체는 stream에 명시적으로 들어가지 않습니다.
Write는 header의 index에서 시작해 먼저 data에 포함된 `n_valid`개 entry를 만들고, 이어지는 `n_invalid`개 위치를 무효화합니다. 그 범위에 이전의 유효 entry가 있으면 함께 invalidate됩니다.
4.78 KVM_PPC_GET_HTAB_FD
------------------------
:Capability: KVM_CAP_PPC_HTAB_FD
:Architectures: powerpc
:Type: vm ioctl
:Parameters: Pointer to struct kvm_get_htab_fd (in)
:Returns: file descriptor number (>= 0) on success, -1 on error
This returns a file descriptor that can be used either to read out the
entries in the guest's hashed page table (HPT), or to write entries to
initialize the HPT. The returned fd can only be written to if the
KVM_GET_HTAB_WRITE bit is set in the flags field of the argument, and
can only be read if that bit is clear. The argument struct looks like
this::
/* For KVM_PPC_GET_HTAB_FD */
struct kvm_get_htab_fd {
__u64 flags;
__u64 start_index;
__u64 reserved[2];
};
/* Values for kvm_get_htab_fd.flags */
#define KVM_GET_HTAB_BOLTED_ONLY ((__u64)0x1)
#define KVM_GET_HTAB_WRITE ((__u64)0x2)
The 'start_index' field gives the index in the HPT of the entry at
which to start reading. It is ignored when writing.
Reads on the fd will initially supply information about all
"interesting" HPT entries. Interesting entries are those with the
bolted bit set, if the KVM_GET_HTAB_BOLTED_ONLY bit is set, otherwise
all entries. When the end of the HPT is reached, the read() will
return. If read() is called again on the fd, it will start again from
the beginning of the HPT, but will only return HPT entries that have
changed since they were last read.
Data read or written is structured as a header (8 bytes) followed by a
series of valid HPT entries (16 bytes) each. The header indicates how
many valid HPT entries there are and how many invalid entries follow
the valid entries. The invalid entries are not represented explicitly
in the stream. The header format is::
struct kvm_get_htab_header {
__u32 index;
__u16 n_valid;
__u16 n_invalid;
};
Writes to the fd create HPT entries starting at the index given in the
header; first 'n_valid' valid entries with contents from the data
written, then 'n_invalid' invalid entries, invalidating any previously
valid entries found.
4.79 KVM_CREATE_DEVICE
3363-3401`KVM_CREATE_DEVICE`는 모든 architecture의 `KVM_CAP_DEVICE_CTRL` VM ioctl이며 kernel 안에 emulated device를 만듭니다. 성공하면 `struct kvm_create_device.fd`에 device handle이 돌아오고 이 fd로 `KVM_SET_DEVICE_ATTR`, `KVM_GET_DEVICE_ATTR`, `KVM_HAS_DEVICE_ATTR`을 호출합니다.
errno의미
`ENODEV`Device type이 알려지지 않았거나 지원되지 않음
`EEXIST`이미 생성되었고 해당 type은 여러 instance를 허용하지 않음
Device type 확인과 instance 수 제한에서 발생하는 대표 오류입니다.
`KVM_CREATE_DEVICE_TEST` flag를 set하면 device type 지원 여부만 검사하고 실제 device는 만들지 않습니다. 현재 VM에서 실제로 생성할 수 있는지까지 보장하는 검사는 아닙니다.
개별 device는 별도 flag를 정의하지 않아야 합니다. Device type 번호만으로 암시되지 않는 동작은 attribute로 지정해야 합니다.
Field방향·의미
`type`입력; `KVM_DEV_TYPE_xxx`
`fd`출력; device handle
`flags`입력; `KVM_CREATE_DEVICE_xxx`
입출력 field 계약입니다.
4.79 KVM_CREATE_DEVICE
----------------------
:Capability: KVM_CAP_DEVICE_CTRL
:Architectures: all
:Type: vm ioctl
:Parameters: struct kvm_create_device (in/out)
:Returns: 0 on success, -1 on error
Errors:
====== =======================================================
ENODEV The device type is unknown or unsupported
EEXIST Device already created, and this type of device may not
be instantiated multiple times
====== =======================================================
Other error conditions may be defined by individual device types or
have their standard meanings.
Creates an emulated device in the kernel. The file descriptor returned
in fd can be used with KVM_SET/GET/HAS_DEVICE_ATTR.
If the KVM_CREATE_DEVICE_TEST flag is set, only test whether the
device type is supported (not necessarily whether it can be created
in the current vm).
Individual devices should not define flags. Attributes should be used
for specifying any behavior that is not implied by the device type
number.
::
struct kvm_create_device {
__u32 type; /* in: KVM_DEV_TYPE_xxx */
__u32 fd; /* out: device handle */
__u32 flags; /* in: KVM_CREATE_DEVICE_xxx */
};
4.80 KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR
3402-3438이 ioctl들은 device fd에서는 `KVM_CAP_DEVICE_CTRL`, VM fd에서는 `KVM_CAP_VM_ATTRIBUTES`, vCPU fd에서는 `KVM_CAP_VCPU_ATTRIBUTES`를 사용합니다. System `/dev/kvm` fd의 `KVM_CAP_SYS_ATTRIBUTES`는 GET만 지원합니다. 문서 대상 architecture는 x86·arm64·s390입니다.
errno의미
`ENXIO`Group 또는 attribute가 알려지지 않았거나 미지원, 또는 hardware support 없음
`EPERM`현재 방식·상태에서 접근 불가; 예: read-only 또는 다른 device state에서만 유효
Group·attribute 지원 여부와 현재 접근 가능 상태를 구분합니다.
호출은 device configuration 또는 state의 지정 부분을 읽거나 씁니다. 정확한 의미는 device별이며 `Documentation/virt/kvm/devices/`의 개별 문서를 따라야 합니다. ONE_REG처럼 전송 data 크기도 특정 attribute가 정의합니다.
Field의미
`flags`현재 정의된 flag 없음
`group`Device가 정의한 group
`attr`Group이 정의한 attribute
`addr`Attribute data의 userspace address
Device별 namespace와 userspace data 위치를 전달합니다.
개별 device type은 위 공통 오류 외에 추가 오류 조건을 정의할 수 있습니다.
4.80 KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR
--------------------------------------------
:Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device,
KVM_CAP_VCPU_ATTRIBUTES for vcpu device
KVM_CAP_SYS_ATTRIBUTES for system (/dev/kvm) device (no set)
:Architectures: x86, arm64, s390
:Type: device ioctl, vm ioctl, vcpu ioctl
:Parameters: struct kvm_device_attr
:Returns: 0 on success, -1 on error
Errors:
===== =============================================================
ENXIO The group or attribute is unknown/unsupported for this device
or hardware support is missing.
EPERM The attribute cannot (currently) be accessed this way
(e.g. read-only attribute, or attribute that only makes
sense when the device is in a different state)
===== =============================================================
Other error conditions may be defined by individual device types.
Gets/sets a specified piece of device configuration and/or state. The
semantics are device-specific. See individual device documentation in
the "devices" directory. As with ONE_REG, the size of the data
transferred is defined by the particular attribute.
::
struct kvm_device_attr {
__u32 flags; /* no flags currently defined */
__u32 group; /* device-defined */
__u64 attr; /* group-defined */
__u64 addr; /* userspace address of attr data */
};
4.81 KVM_HAS_DEVICE_ATTR
3439-3460`KVM_HAS_DEVICE_ATTR`은 device·VM·vCPU·system fd에서 특정 device attribute 구현 여부를 검사합니다. Capability는 각각 `KVM_CAP_DEVICE_CTRL`, `KVM_CAP_VM_ATTRIBUTES`, `KVM_CAP_VCPU_ATTRIBUTES`, `KVM_CAP_SYS_ATTRIBUTES`입니다.
성공 반환 0은 attribute가 구현되었다는 뜻이지만 device의 현재 상태에서 읽거나 쓸 수 있다는 뜻은 아닙니다. Probe 과정에서는 `struct kvm_device_attr.addr`를 무시합니다.
Group 또는 attribute가 알려지지 않았거나 지원되지 않거나 필요한 hardware support가 없으면 `ENXIO`를 반환합니다.
4.81 KVM_HAS_DEVICE_ATTR
------------------------
:Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device,
KVM_CAP_VCPU_ATTRIBUTES for vcpu device
KVM_CAP_SYS_ATTRIBUTES for system (/dev/kvm) device
:Type: device ioctl, vm ioctl, vcpu ioctl
:Parameters: struct kvm_device_attr
:Returns: 0 on success, -1 on error
Errors:
===== =============================================================
ENXIO The group or attribute is unknown/unsupported for this device
or hardware support is missing.
===== =============================================================
Tests whether a device supports a particular attribute. A successful
return indicates the attribute is implemented. It does not necessarily
indicate that the attribute can be read or written in the device's
current state. "addr" is ignored.
4.82 KVM_ARM_VCPU_INIT
3461-3572`KVM_ARM_VCPU_INIT`은 arm64 basic vCPU ioctl입니다. Guest에 보일 CPU target과 optional feature를 `struct kvm_vcpu_init`으로 지정하고 CPU register를 초기값으로 reset합니다. 호출하지 않으면 해당 vCPU의 `KVM_RUN`이 `ENOEXEC`를 반환합니다.
errno의미
`EINVAL`알 수 없는 target 또는 유효하지 않은 feature 조합
`ENOENT`지정한 feature bit를 알 수 없음
Target과 feature bitmap 유효성을 검사합니다.
대상초기 상태
AArch64 processor stateEL1h, D·A·I·F bit set, 나머지 clear
AArch32 processor stateSVC, A·I·F bit set, 나머지 clear
General purpose, PC, SP0
FPSIMD/NEON0
SVE0
System registerEL1/SVC warm reset 값; EL2 enable 시 EL2 reset 값
CPU mode와 register class별 reset 값입니다.
일부 register는 machine topology를 반영하므로 이 ioctl을 호출하기 전에 모든 vCPU를 만들어야 합니다.
같은 vCPU에 실행 후를 포함해 여러 번 호출할 수 있고 매번 초기 상태로 reset합니다. 다만 최초 호출 뒤에는 항상 같은 target과 같은 feature flag set을 사용해야 하며 다르면 `EINVAL`입니다.
Feature효과·요구 조건
`KVM_ARM_VCPU_POWER_OFF`Power-off 상태로 시작; `KVM_CAP_ARM_PSCI` 필요
`KVM_ARM_VCPU_EL1_32BIT`32-bit mode로 시작; `KVM_CAP_ARM_EL1_32BIT` 필요
`KVM_ARM_VCPU_PSCI_0_2`PSCI 0.2 호환 emulation; `KVM_CAP_ARM_PSCI_0_2` 필요
`KVM_ARM_VCPU_PMU_V3`PMUv3 emulation; `KVM_CAP_ARM_PMU_V3` 필요
`KVM_ARM_VCPU_PTRAUTH_ADDRESS`Address pointer authentication; 대응 capability 필요
`KVM_ARM_VCPU_PTRAUTH_GENERIC`Generic pointer authentication; 대응 capability 필요
`KVM_ARM_VCPU_SVE`SVE enable; `KVM_CAP_ARM_SVE`와 finalize 필요
`KVM_ARM_VCPU_HAS_EL2`EL2에서 boot하는 nested virtualization; 기본 VHE E2H=RES1
`KVM_ARM_VCPU_HAS_EL2_E2H0`Nested virtualization을 non-VHE E2H=RES0로 제한; HAS_EL2도 필요
각 feature의 효과와 capability 의존성입니다.
Address와 Generic pointer authentication capability가 둘 다 존재하면 두 feature를 모두 요청하거나 모두 요청하지 않아야 합니다.
SVE를 요청한 뒤 finalize 전에는 `KVM_RUN`, `KVM_GET_REG_LIST`, scalable Zn·Pn·FFR의 ONE_REG 접근이 불가능합니다. 이 기간에는 `KVM_REG_ARM64_SVE_VLS`를 읽어 host 최적 vector-length set을 얻고 필요하면 써서 조정할 수 있습니다. `KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE)` 뒤에는 VLS가 immutable입니다.
`KVM_ARM_VCPU_HAS_EL2`만 설정하면 `HCR_EL2.E2H`는 RES1인 VHE mode입니다. `KVM_ARM_VCPU_HAS_EL2_E2H0`를 함께 설정하면 RES0인 non-VHE mode로 제한됩니다.
.. _KVM_ARM_VCPU_INIT:
4.82 KVM_ARM_VCPU_INIT
----------------------
:Capability: basic
:Architectures: arm64
:Type: vcpu ioctl
:Parameters: struct kvm_vcpu_init (in)
:Returns: 0 on success; -1 on error
Errors:
====== =================================================================
EINVAL the target is unknown, or the combination of features is invalid.
ENOENT a features bit specified is unknown.
====== =================================================================
This tells KVM what type of CPU to present to the guest, and what
optional features it should have. This will cause a reset of the cpu
registers to their initial values. If this is not called, KVM_RUN will
return ENOEXEC for that vcpu.
The initial values are defined as:
- Processor state:
* AArch64: EL1h, D, A, I and F bits set. All other bits
are cleared.
* AArch32: SVC, A, I and F bits set. All other bits are
cleared.
- General Purpose registers, including PC and SP: set to 0
- FPSIMD/NEON registers: set to 0
- SVE registers: set to 0
- System registers: Reset to their architecturally defined
values as for a warm reset to EL1 (resp. SVC) or EL2 (in the
case of EL2 being enabled).
Note that because some registers reflect machine topology, all vcpus
should be created before this ioctl is invoked.
Userspace can call this function multiple times for a given vcpu, including
after the vcpu has been run. This will reset the vcpu to its initial
state. All calls to this function after the initial call must use the same
target and same set of feature flags, otherwise EINVAL will be returned.
Possible features:
- KVM_ARM_VCPU_POWER_OFF: Starts the CPU in a power-off state.
Depends on KVM_CAP_ARM_PSCI. If not set, the CPU will be powered on
and execute guest code when KVM_RUN is called.
- KVM_ARM_VCPU_EL1_32BIT: Starts the CPU in a 32bit mode.
Depends on KVM_CAP_ARM_EL1_32BIT (arm64 only).
- KVM_ARM_VCPU_PSCI_0_2: Emulate PSCI v0.2 (or a future revision
backward compatible with v0.2) for the CPU.
Depends on KVM_CAP_ARM_PSCI_0_2.
- KVM_ARM_VCPU_PMU_V3: Emulate PMUv3 for the CPU.
Depends on KVM_CAP_ARM_PMU_V3.
- KVM_ARM_VCPU_PTRAUTH_ADDRESS: Enables Address Pointer authentication
for arm64 only.
Depends on KVM_CAP_ARM_PTRAUTH_ADDRESS.
If KVM_CAP_ARM_PTRAUTH_ADDRESS and KVM_CAP_ARM_PTRAUTH_GENERIC are
both present, then both KVM_ARM_VCPU_PTRAUTH_ADDRESS and
KVM_ARM_VCPU_PTRAUTH_GENERIC must be requested or neither must be
requested.
- KVM_ARM_VCPU_PTRAUTH_GENERIC: Enables Generic Pointer authentication
for arm64 only.
Depends on KVM_CAP_ARM_PTRAUTH_GENERIC.
If KVM_CAP_ARM_PTRAUTH_ADDRESS and KVM_CAP_ARM_PTRAUTH_GENERIC are
both present, then both KVM_ARM_VCPU_PTRAUTH_ADDRESS and
KVM_ARM_VCPU_PTRAUTH_GENERIC must be requested or neither must be
requested.
- KVM_ARM_VCPU_SVE: Enables SVE for the CPU (arm64 only).
Depends on KVM_CAP_ARM_SVE.
Requires KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE):
* After KVM_ARM_VCPU_INIT:
- KVM_REG_ARM64_SVE_VLS may be read using KVM_GET_ONE_REG: the
initial value of this pseudo-register indicates the best set of
vector lengths possible for a vcpu on this host.
* Before KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE):
- KVM_RUN and KVM_GET_REG_LIST are not available;
- KVM_GET_ONE_REG and KVM_SET_ONE_REG cannot be used to access
the scalable architectural SVE registers
KVM_REG_ARM64_SVE_ZREG(), KVM_REG_ARM64_SVE_PREG() or
KVM_REG_ARM64_SVE_FFR;
- KVM_REG_ARM64_SVE_VLS may optionally be written using
KVM_SET_ONE_REG, to modify the set of vector lengths available
for the vcpu.
* After KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE):
- the KVM_REG_ARM64_SVE_VLS pseudo-register is immutable, and can
no longer be written using KVM_SET_ONE_REG.
- KVM_ARM_VCPU_HAS_EL2: Enable Nested Virtualisation support,
booting the guest from EL2 instead of EL1.
Depends on KVM_CAP_ARM_EL2.
The VM is running with HCR_EL2.E2H being RES1 (VHE) unless
KVM_ARM_VCPU_HAS_EL2_E2H0 is also set.
- KVM_ARM_VCPU_HAS_EL2_E2H0: Restrict Nested Virtualisation
support to HCR_EL2.E2H being RES0 (non-VHE).
Depends on KVM_CAP_ARM_EL2_E2H0.
KVM_ARM_VCPU_HAS_EL2 must also be set.
4.83 KVM_ARM_PREFERRED_TARGET
3573-3601`KVM_ARM_PREFERRED_TARGET`은 arm64 basic VM ioctl로 현재 host에서 KVM이 emulate하기에 선호하는 CPU target type을 조회합니다. 선호 target이 없으면 `ENODEV`입니다.
출력 `struct kvm_vcpu_init`에는 preferred target과 권장 feature가 들어갑니다. `features` bitmap에 set된 bit는 권장 사항이며 반드시 적용해야 하는 것은 아닙니다.
반환 정보를 바탕으로 `KVM_ARM_VCPU_INIT` 입력을 준비하면 underlying host와 맞는 vCPU를 만들 수 있습니다.
4.83 KVM_ARM_PREFERRED_TARGET
-----------------------------
:Capability: basic
:Architectures: arm64
:Type: vm ioctl
:Parameters: struct kvm_vcpu_init (out)
:Returns: 0 on success; -1 on error
Errors:
====== ==========================================
ENODEV no preferred target available for the host
====== ==========================================
This queries KVM for preferred CPU target type which can be emulated
by KVM on underlying host.
The ioctl returns struct kvm_vcpu_init instance containing information
about preferred CPU target type and recommended features for it. The
kvm_vcpu_init->features bitmap returned will have feature bits set if
the preferred target recommends setting these features, but this is
not mandatory.
The information returned by this ioctl can be used to prepare an instance
of struct kvm_vcpu_init for KVM_ARM_VCPU_INIT ioctl which will result in
VCPU matching underlying host.
4.84 KVM_GET_REG_LIST
3602-3651`KVM_GET_REG_LIST`는 arm64·MIPS·RISC-V, 그리고 `KVM_CAP_ONE_REG`가 있는 x86의 basic vCPU ioctl입니다. `KVM_GET_ONE_REG`·`KVM_SET_ONE_REG`으로 접근할 수 있는 guest register ID를 `struct kvm_reg_list`에 반환합니다.
Userspace가 제공한 `reg[]` capacity보다 목록이 크면 `E2BIG`을 반환하고 필요한 entry 수를 `n`에 씁니다. 구조체의 `n`은 register 수이고 뒤에 가변 길이 `__u64 reg[]`가 이어집니다.
s390은 역사적 이유로 `KVM_GET_REG_LIST`를 지원하지 않습니다. Kernel 4.x 이후 ONE_REG set에는 `TODPR`, `EPOCHDIFF`, `CPU_TIMER`, `CLOCK_COMP`, `PFTOKEN`, `PFCOMPARE`, `PFSELECT`, `PP`, `GBEA`가 포함됩니다.
x86의 `KVM_GET_MSR_INDEX_LIST`가 열거하는 모든 MSR은 `KVM_X86_REG_TYPE_MSR`로 ONE_REG 접근을 지원하지만 `KVM_GET_REG_LIST` 결과에는 열거되지 않습니다.
4.84 KVM_GET_REG_LIST
---------------------
:Capability: basic
:Architectures: arm64, mips, riscv, x86 (if KVM_CAP_ONE_REG)
:Type: vcpu ioctl
:Parameters: struct kvm_reg_list (in/out)
:Returns: 0 on success; -1 on error
Errors:
===== ==============================================================
E2BIG the reg index list is too big to fit in the array specified by
the user (the number required will be written into n).
===== ==============================================================
::
struct kvm_reg_list {
__u64 n; /* number of registers in reg[] */
__u64 reg[0];
};
This ioctl returns the guest registers that are supported for the
KVM_GET_ONE_REG/KVM_SET_ONE_REG calls.
Note that s390 does not support KVM_GET_REG_LIST for historical reasons
(read: nobody cared). The set of registers in kernels 4.x and newer is:
- KVM_REG_S390_TODPR
- KVM_REG_S390_EPOCHDIFF
- KVM_REG_S390_CPU_TIMER
- KVM_REG_S390_CLOCK_COMP
- KVM_REG_S390_PFTOKEN
- KVM_REG_S390_PFCOMPARE
- KVM_REG_S390_PFSELECT
- KVM_REG_S390_PP
- KVM_REG_S390_GBEA
Note, for x86, all MSRs enumerated by KVM_GET_MSR_INDEX_LIST are supported as
type KVM_X86_REG_TYPE_MSR, but are NOT enumerated via KVM_GET_REG_LIST.
4.85 KVM_ARM_SET_DEVICE_ADDR (deprecated)
3652-3700Deprecated `KVM_ARM_SET_DEVICE_ADDR`은 arm64 `KVM_CAP_ARM_SET_DEVICE_ADDR` VM ioctl로 host kernel이 알아야 하는 emulated 또는 직접 노출 device의 guest physical address를 지정합니다.
errno의미
`ENODEV`알 수 없는 device ID
`ENXIO`현재 system에서 device 미지원
`EEXIST`Address가 이미 설정됨
`E2BIG`Guest physical address space 밖의 address
`EBUSY`다른 device range와 겹침
Device와 guest physical mapping의 유효성을 검사합니다.
입력은 64-bit `id`와 `addr`를 가진 `struct kvm_arm_device_addr`입니다. arm64의 `id`는 상위 32 bit가 0이고 bit 31:16이 device ID, bit 15:0이 device별 address-type ID입니다.
현재 이 API가 필요한 경우는 kernel GIC의 hardware VGIC 기능이며 device ID로 `KVM_ARM_DEVICE_VGIC_V2`를 사용합니다. VGIC virtual CPU·distributor interface base는 `KVM_CREATE_IRQCHIP` 뒤, 어떤 vCPU의 `KVM_RUN`보다 전에 설정해야 합니다. 같은 base를 두 번 설정하면 `EEXIST`입니다.
이 ioctl은 폐기되었으며 더 유연한 `KVM_SET_DEVICE_ATTR`·`KVM_GET_DEVICE_ATTR` API를 사용해야 합니다.
4.85 KVM_ARM_SET_DEVICE_ADDR (deprecated)
-----------------------------------------
:Capability: KVM_CAP_ARM_SET_DEVICE_ADDR
:Architectures: arm64
:Type: vm ioctl
:Parameters: struct kvm_arm_device_address (in)
:Returns: 0 on success, -1 on error
Errors:
====== ============================================
ENODEV The device id is unknown
ENXIO Device not supported on current system
EEXIST Address already set
E2BIG Address outside guest physical address space
EBUSY Address overlaps with other device range
====== ============================================
::
struct kvm_arm_device_addr {
__u64 id;
__u64 addr;
};
Specify a device address in the guest's physical address space where guests
can access emulated or directly exposed devices, which the host kernel needs
to know about. The id field is an architecture specific identifier for a
specific device.
arm64 divides the id field into two parts, a device id and an
address type id specific to the individual device::
bits: | 63 ... 32 | 31 ... 16 | 15 ... 0 |
field: | 0x00000000 | device id | addr type id |
arm64 currently only require this when using the in-kernel GIC
support for the hardware VGIC features, using KVM_ARM_DEVICE_VGIC_V2
as the device id. When setting the base address for the guest's
mapping of the VGIC virtual CPU and distributor interface, the ioctl
must be called after calling KVM_CREATE_IRQCHIP, but before calling
KVM_RUN on any of the VCPUs. Calling this ioctl twice for any of the
base addresses will return -EEXIST.
Note, this IOCTL is deprecated and the more flexible SET/GET_DEVICE_ATTR API
should be used instead.
4.86 KVM_PPC_RTAS_DEFINE_TOKEN
3701-3720`KVM_PPC_RTAS_DEFINE_TOKEN`은 PowerPC `KVM_CAP_PPC_RTAS` VM ioctl입니다. Kernel 구현이 있는 RTAS service 이름과 token 값을 연결해 guest의 RTAS call을 kernel에서 처리하게 합니다.
Token이 0이 아니면 해당 service에 연결되고 이후 guest가 그 token으로 호출한 RTAS request를 kernel이 처리합니다.
Token 값 0은 service와 연결된 기존 token을 잊게 합니다. 이후 해당 service의 guest RTAS call은 userspace로 전달되어 처리됩니다.
4.86 KVM_PPC_RTAS_DEFINE_TOKEN
------------------------------
:Capability: KVM_CAP_PPC_RTAS
:Architectures: ppc
:Type: vm ioctl
:Parameters: struct kvm_rtas_token_args
:Returns: 0 on success, -1 on error
Defines a token value for a RTAS (Run Time Abstraction Services)
service in order to allow it to be handled in the kernel. The
argument struct gives the name of the service, which must be the name
of a service that has a kernel-side implementation. If the token
value is non-zero, it will be associated with that service, and
subsequent RTAS calls by the guest specifying that token will be
handled by the kernel. If the token value is 0, then any token
associated with the service will be forgotten, and subsequent RTAS
calls by the guest for that service will be passed to userspace to be
handled.
4.87 KVM_SET_GUEST_DEBUG
3721-3781`KVM_SET_GUEST_DEBUG`는 x86·s390·PowerPC·arm64의 `KVM_CAP_SET_GUEST_DEBUG` vCPU ioctl입니다. Architecture별 debug register를 설정하고 실행 중 처리할 guest debug event를 구성합니다.
`struct kvm_guest_debug`는 32-bit `control`, padding, architecture별 `struct kvm_guest_debug_arch`로 구성됩니다.
Bit의미
`KVM_GUESTDBG_ENABLE`Guest debugging enable
`KVM_GUESTDBG_SINGLESTEP`다음 실행을 single-step
모든 지원 architecture가 공유하는 기본 bit입니다.
Flag대상·의미
`KVM_GUESTDBG_USE_SW_BP`x86·arm64 software breakpoint
`KVM_GUESTDBG_USE_HW_BP`x86·s390 hardware breakpoint
`KVM_GUESTDBG_USE_HW`arm64 hardware debug event
`KVM_GUESTDBG_INJECT_DB`x86 DB exception 주입
`KVM_GUESTDBG_INJECT_BP`x86 BP exception 주입
`KVM_GUESTDBG_EXIT_PENDING`s390 즉시 guest exit
`KVM_GUESTDBG_BLOCKIRQ`x86 interrupt·NMI·SMI 주입 방지
control 상위 16 bit에 들어갈 수 있는 flag입니다.
Software breakpoint를 사용하면 breakpoint exception이 일반 guest vector로 흘러가지 않고 정확히 trap되어 KVM run loop가 breakpoint에서 빠져나와야 합니다. Hardware breakpoint를 사용하면 vCPU의 architecture별 register를 제공된 값으로 갱신해야 합니다.
arm64가 지원하는 hardware breakpoint·watchpoint register 수는 각각 `KVM_CAP_GUEST_DEBUG_HW_BPS`, `KVM_CAP_GUEST_DEBUG_HW_WPS`의 양수 반환값으로 조회합니다. PowerPC의 `KVM_CAP_PPC_GUEST_DEBUG_SSTEP`은 single-step 지원을 나타냅니다.
지원되는 경우 `KVM_CAP_SET_GUEST_DEBUG2`는 `control`에서 사용할 수 있는 `KVM_GUESTDBG_*` bit를 나타냅니다. Debug event가 발생하면 `KVM_EXIT_DEBUG`로 run loop를 나가며 `kvm_run.kvm_debug_exit_arch`가 architecture별 정보를 담습니다.
4.87 KVM_SET_GUEST_DEBUG
------------------------
:Capability: KVM_CAP_SET_GUEST_DEBUG
:Architectures: x86, s390, ppc, arm64
:Type: vcpu ioctl
:Parameters: struct kvm_guest_debug (in)
:Returns: 0 on success; -1 on error
::
struct kvm_guest_debug {
__u32 control;
__u32 pad;
struct kvm_guest_debug_arch arch;
};
Set up the processor specific debug registers and configure vcpu for
handling guest debug events. There are two parts to the structure, the
first a control bitfield indicates the type of debug events to handle
when running. Common control bits are:
- KVM_GUESTDBG_ENABLE: guest debugging is enabled
- KVM_GUESTDBG_SINGLESTEP: the next run should single-step
The top 16 bits of the control field are architecture specific control
flags which can include the following:
- KVM_GUESTDBG_USE_SW_BP: using software breakpoints [x86, arm64]
- KVM_GUESTDBG_USE_HW_BP: using hardware breakpoints [x86, s390]
- KVM_GUESTDBG_USE_HW: using hardware debug events [arm64]
- KVM_GUESTDBG_INJECT_DB: inject DB type exception [x86]
- KVM_GUESTDBG_INJECT_BP: inject BP type exception [x86]
- KVM_GUESTDBG_EXIT_PENDING: trigger an immediate guest exit [s390]
- KVM_GUESTDBG_BLOCKIRQ: avoid injecting interrupts/NMI/SMI [x86]
For example KVM_GUESTDBG_USE_SW_BP indicates that software breakpoints
are enabled in memory so we need to ensure breakpoint exceptions are
correctly trapped and the KVM run loop exits at the breakpoint and not
running off into the normal guest vector. For KVM_GUESTDBG_USE_HW_BP
we need to ensure the guest vCPUs architecture specific registers are
updated to the correct (supplied) values.
The second part of the structure is architecture specific and
typically contains a set of debug registers.
For arm64 the number of debug registers is implementation defined and
can be determined by querying the KVM_CAP_GUEST_DEBUG_HW_BPS and
KVM_CAP_GUEST_DEBUG_HW_WPS capabilities which return a positive number
indicating the number of supported registers.
For ppc, the KVM_CAP_PPC_GUEST_DEBUG_SSTEP capability indicates whether
the single-step debug event (KVM_GUESTDBG_SINGLESTEP) is supported.
Also when supported, KVM_CAP_SET_GUEST_DEBUG2 capability indicates the
supported KVM_GUESTDBG_* bits in the control field.
When debug events exit the main run loop with the reason
KVM_EXIT_DEBUG with the kvm_debug_exit_arch part of the kvm_run
structure containing architecture specific debug information.
4.88 KVM_GET_EMULATED_CPUID
3782-3856`KVM_GET_EMULATED_CPUID`는 x86 `KVM_CAP_EXT_EMUL_CPUID` system ioctl입니다. Host CPU에 native로 존재하는 feature가 아니라 KVM이 emulate하는 CPUID feature를 `struct kvm_cpuid2`로 조회합니다.
입력 `nent`는 가변 `entries[]`의 capacity입니다. 너무 작으면 `E2BIG`, 너무 크면 `nent`를 조정하고 `ENOMEM`을 반환합니다. 정확하면 유효 entry 수로 `nent`를 갱신하고 배열을 채웁니다.
각 entry는 KVM이 emulate하는 feature에 해당하는 CPUID set bit만 담고 알 수 없거나 지원하지 않는 bit는 clear합니다. x2APIC처럼 host CPU에는 없지만 효율적으로 emulate할 수 있어 `KVM_GET_SUPPORTED_CPUID`에 노출되는 feature는 이 목록에 포함되지 않을 수 있습니다.
Field의미
`function`Entry를 얻을 때 EAX input
`index`ECX에 영향받는 leaf의 ECX input
`KVM_CPUID_FLAG_SIGNIFCANT_INDEX`index field가 유효함
`eax`, `ebx`, `ecx`, `edx`해당 function/index의 CPUID 결과
CPUID instruction input과 출력 register를 그대로 표현합니다.
`KVM_CPUID_FLAG_STATEFUL_FUNC`와 `KVM_CPUID_FLAG_STATE_READ_NEXT`는 deprecated입니다. `kvm_cpuid2.flags`는 userspace에서 flag를 전달하는 데 사용합니다.
4.88 KVM_GET_EMULATED_CPUID
---------------------------
:Capability: KVM_CAP_EXT_EMUL_CPUID
:Architectures: x86
:Type: system ioctl
:Parameters: struct kvm_cpuid2 (in/out)
:Returns: 0 on success, -1 on error
::
struct kvm_cpuid2 {
__u32 nent;
__u32 flags;
struct kvm_cpuid_entry2 entries[0];
};
The member 'flags' is used for passing flags from userspace.
::
#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0)
#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1) /* deprecated */
#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2) /* deprecated */
struct kvm_cpuid_entry2 {
__u32 function;
__u32 index;
__u32 flags;
__u32 eax;
__u32 ebx;
__u32 ecx;
__u32 edx;
__u32 padding[3];
};
This ioctl returns x86 cpuid features which are emulated by
kvm.Userspace can use the information returned by this ioctl to query
which features are emulated by kvm instead of being present natively.
Userspace invokes KVM_GET_EMULATED_CPUID by passing a kvm_cpuid2
structure with the 'nent' field indicating the number of entries in
the variable-size array 'entries'. If the number of entries is too low
to describe the cpu capabilities, an error (E2BIG) is returned. If the
number is too high, the 'nent' field is adjusted and an error (ENOMEM)
is returned. If the number is just right, the 'nent' field is adjusted
to the number of valid entries in the 'entries' array, which is then
filled.
The entries returned are the set CPUID bits of the respective features
which kvm emulates, as returned by the CPUID instruction, with unknown
or unsupported feature bits cleared.
Features like x2apic, for example, may not be present in the host cpu
but are exposed by kvm in KVM_GET_SUPPORTED_CPUID because they can be
emulated efficiently and thus not included here.
The fields in each entry are defined as follows:
function:
the eax value used to obtain the entry
index:
the ecx value used to obtain the entry (for entries that are
affected by ecx)
flags:
an OR of zero or more of the following:
KVM_CPUID_FLAG_SIGNIFCANT_INDEX:
if the index field is valid
eax, ebx, ecx, edx:
the values returned by the cpuid instruction for
this function/index combination
4.89 KVM_S390_MEM_OP
3857-4001`KVM_S390_MEM_OP`은 s390 VM 또는 vCPU ioctl로 guest memory를 읽거나 씁니다. 기능 범위는 `KVM_CAP_S390_MEM_OP_EXTENSION`이 나타냅니다. 성공은 0, 일반 오류는 음수, access가 program exception을 일으키면 16-bit exception code를 반환합니다.
Field의미
`gaddr`Guest 시작 address
`flags`Operation 수정 flag; 정의되지 않은 bit는 0
`size`Byte 수; 0 불가, 최대값은 capability 반환값
`op`Operation 종류
`buf`Read destination 또는 write source userspace buffer
`ar`Logical access register 번호 0~15
`key`Storage-key protection access key 0~15
`old_addr`Absolute cmpxchg 비교값 pointer
`sida_offset`SIDA 내부 offset
공통 주소·buffer와 operation별 보조 field입니다.
`size`는 0일 수 없고 최대값은 `KVM_CAP_S390_MEM_OP`으로 조회합니다. Reserved·unused 값은 무시하며 향후 member 추가는 새 flag와 함께 이루어져야 합니다.
Operation대상·방향
`KVM_S390_MEMOP_LOGICAL_READ/WRITE`vCPU state로 logical address를 translate하여 접근
`KVM_S390_MEMOP_ABSOLUTE_READ/WRITE`Absolute guest memory 접근
`KVM_S390_MEMOP_ABSOLUTE_CMPXCHG`Absolute memory atomic compare-exchange
`KVM_S390_MEMOP_SIDA_READ/WRITE`Protected guest의 secure instruction data area
`op`가 선택하는 접근 방식입니다.
Logical access는 vCPU state와 `ar`가 지정한 access register로 guest logical address를 absolute address로 translate합니다. vCPU ioctl에서만, non-protected guest에만 허용됩니다.
Logical read/write는 `KVM_S390_MEMOP_F_CHECK_ONLY`, `KVM_S390_MEMOP_F_INJECT_EXCEPTION`, `KVM_S390_MEMOP_F_SKEY_PROTECTION`을 지원합니다. CHECK_ONLY는 실제 memory data에 접근하지 않고 exception 발생 여부만 검사하므로 `buf`가 NULL이어도 됩니다.
Access exception이 발생하거나 CHECK_ONLY에서 발생할 것으로 판정되면 양수 exception code를 반환합니다. INJECT_EXCEPTION도 set하면 해당 vCPU에 exception을 직접 주입합니다. 별도 언급이 없으면 protection exception의 TEID는 suppression을 나타냅니다.
SKEY_PROTECTION은 `key` 0~15를 적용해 storage-key access를 검사하며 extension capability가 0보다 클 때 사용할 수 있습니다. 여러 page의 key가 다르면 일부 memory를 수정한 뒤 protection exception이 생길 수 있고, 이 경우 주입된 TEID는 suppression을 나타내지 않습니다.
Absolute read/write는 storage-key 검사와 memory access를 하나의 operation으로 묶어 검사와 접근 사이 지연을 피하려는 API입니다. `KVM_S390_MEMOP_EXTENSION_CAP_BASE`가 있을 때 VM ioctl에서 허용되고 현재 vCPU ioctl에서는 허용되지 않으며 non-protected guest 전용입니다.
Absolute access는 CHECK_ONLY와 SKEY_PROTECTION을 지원하며 의미는 logical access와 같습니다.
Absolute cmpxchg는 target이 `old_addr`가 가리키는 값과 같을 때만 write하는 atomic operation입니다. `size`는 16 이하의 2의 거듭제곱이어야 합니다. 값이 달라 교환하지 못하면 target 값을 `old_addr` buffer에 써서 userspace가 성공 여부를 판별하게 합니다.
Cmpxchg는 `KVM_S390_MEMOP_EXTENSION_CAP_CMPXCHG`가 있을 때 VM ioctl에서 허용되고 SKEY_PROTECTION flag를 지원합니다.
SIDA read/write는 protected guest instruction emulation에 필요한 memory operand가 있는 secure instruction data area에 접근합니다. `KVM_CAP_S390_PROTECTED`가 있을 때 protected guest의 vCPU ioctl에서만 허용되며 지원 flag는 없습니다.
4.89 KVM_S390_MEM_OP
--------------------
:Capability: KVM_CAP_S390_MEM_OP, KVM_CAP_S390_PROTECTED, KVM_CAP_S390_MEM_OP_EXTENSION
:Architectures: s390
:Type: vm ioctl, vcpu ioctl
:Parameters: struct kvm_s390_mem_op (in)
:Returns: = 0 on success,
< 0 on generic error (e.g. -EFAULT or -ENOMEM),
16 bit program exception code if the access causes such an exception
Read or write data from/to the VM's memory.
The KVM_CAP_S390_MEM_OP_EXTENSION capability specifies what functionality is
supported.
Parameters are specified via the following structure::
struct kvm_s390_mem_op {
__u64 gaddr; /* the guest address */
__u64 flags; /* flags */
__u32 size; /* amount of bytes */
__u32 op; /* type of operation */
__u64 buf; /* buffer in userspace */
union {
struct {
__u8 ar; /* the access register number */
__u8 key; /* access key, ignored if flag unset */
__u8 pad1[6]; /* ignored */
__u64 old_addr; /* ignored if flag unset */
};
__u32 sida_offset; /* offset into the sida */
__u8 reserved[32]; /* ignored */
};
};
The start address of the memory region has to be specified in the "gaddr"
field, and the length of the region in the "size" field (which must not
be 0). The maximum value for "size" can be obtained by checking the
KVM_CAP_S390_MEM_OP capability. "buf" is the buffer supplied by the
userspace application where the read data should be written to for
a read access, or where the data that should be written is stored for
a write access. The "reserved" field is meant for future extensions.
Reserved and unused values are ignored. Future extension that add members must
introduce new flags.
The type of operation is specified in the "op" field. Flags modifying
their behavior can be set in the "flags" field. Undefined flag bits must
be set to 0.
Possible operations are:
* ``KVM_S390_MEMOP_LOGICAL_READ``
* ``KVM_S390_MEMOP_LOGICAL_WRITE``
* ``KVM_S390_MEMOP_ABSOLUTE_READ``
* ``KVM_S390_MEMOP_ABSOLUTE_WRITE``
* ``KVM_S390_MEMOP_SIDA_READ``
* ``KVM_S390_MEMOP_SIDA_WRITE``
* ``KVM_S390_MEMOP_ABSOLUTE_CMPXCHG``
Logical read/write:
^^^^^^^^^^^^^^^^^^^
Access logical memory, i.e. translate the given guest address to an absolute
address given the state of the VCPU and use the absolute address as target of
the access. "ar" designates the access register number to be used; the valid
range is 0..15.
Logical accesses are permitted for the VCPU ioctl only.
Logical accesses are permitted for non-protected guests only.
Supported flags:
* ``KVM_S390_MEMOP_F_CHECK_ONLY``
* ``KVM_S390_MEMOP_F_INJECT_EXCEPTION``
* ``KVM_S390_MEMOP_F_SKEY_PROTECTION``
The KVM_S390_MEMOP_F_CHECK_ONLY flag can be set to check whether the
corresponding memory access would cause an access exception; however,
no actual access to the data in memory at the destination is performed.
In this case, "buf" is unused and can be NULL.
In case an access exception occurred during the access (or would occur
in case of KVM_S390_MEMOP_F_CHECK_ONLY), the ioctl returns a positive
error number indicating the type of exception. This exception is also
raised directly at the corresponding VCPU if the flag
KVM_S390_MEMOP_F_INJECT_EXCEPTION is set.
On protection exceptions, unless specified otherwise, the injected
translation-exception identifier (TEID) indicates suppression.
If the KVM_S390_MEMOP_F_SKEY_PROTECTION flag is set, storage key
protection is also in effect and may cause exceptions if accesses are
prohibited given the access key designated by "key"; the valid range is 0..15.
KVM_S390_MEMOP_F_SKEY_PROTECTION is available if KVM_CAP_S390_MEM_OP_EXTENSION
is > 0.
Since the accessed memory may span multiple pages and those pages might have
different storage keys, it is possible that a protection exception occurs
after memory has been modified. In this case, if the exception is injected,
the TEID does not indicate suppression.
Absolute read/write:
^^^^^^^^^^^^^^^^^^^^
Access absolute memory. This operation is intended to be used with the
KVM_S390_MEMOP_F_SKEY_PROTECTION flag, to allow accessing memory and performing
the checks required for storage key protection as one operation (as opposed to
user space getting the storage keys, performing the checks, and accessing
memory thereafter, which could lead to a delay between check and access).
Absolute accesses are permitted for the VM ioctl if KVM_CAP_S390_MEM_OP_EXTENSION
has the KVM_S390_MEMOP_EXTENSION_CAP_BASE bit set.
Currently absolute accesses are not permitted for VCPU ioctls.
Absolute accesses are permitted for non-protected guests only.
Supported flags:
* ``KVM_S390_MEMOP_F_CHECK_ONLY``
* ``KVM_S390_MEMOP_F_SKEY_PROTECTION``
The semantics of the flags common with logical accesses are as for logical
accesses.
Absolute cmpxchg:
^^^^^^^^^^^^^^^^^
Perform cmpxchg on absolute guest memory. Intended for use with the
KVM_S390_MEMOP_F_SKEY_PROTECTION flag.
Instead of doing an unconditional write, the access occurs only if the target
location contains the value pointed to by "old_addr".
This is performed as an atomic cmpxchg with the length specified by the "size"
parameter. "size" must be a power of two up to and including 16.
If the exchange did not take place because the target value doesn't match the
old value, the value "old_addr" points to is replaced by the target value.
User space can tell if an exchange took place by checking if this replacement
occurred. The cmpxchg op is permitted for the VM ioctl if
KVM_CAP_S390_MEM_OP_EXTENSION has flag KVM_S390_MEMOP_EXTENSION_CAP_CMPXCHG set.
Supported flags:
* ``KVM_S390_MEMOP_F_SKEY_PROTECTION``
SIDA read/write:
^^^^^^^^^^^^^^^^
Access the secure instruction data area which contains memory operands necessary
for instruction emulation for protected guests.
SIDA accesses are available if the KVM_CAP_S390_PROTECTED capability is available.
SIDA accesses are permitted for the VCPU ioctl only.
SIDA accesses are permitted for protected guests only.
No flags are supported.
4.90 KVM_S390_GET_SKEYS
4002-4033`KVM_S390_GET_SKEYS`는 s390 `KVM_CAP_S390_SKEYS` VM ioctl로 guest storage key를 읽습니다. 성공은 0, guest가 storage key를 사용하지 않으면 `KVM_S390_GET_SKEYS_NONE`, 오류면 음수를 반환합니다.
`struct kvm_s390_skeys.start_gfn`은 첫 guest frame 번호이고 `count`는 그 지점부터 연속으로 읽을 frame 수입니다. `count`는 1 이상 `KVM_S390_SKEYS_MAX` 이하여야 하며 범위를 벗어나면 `EINVAL`입니다.
`skeydata_addr`는 `count` byte를 담을 수 있는 userspace buffer 주소이며 ioctl이 frame별 storage-key data로 채웁니다. `flags`와 `reserved[9]`도 구조체에 포함됩니다.
4.90 KVM_S390_GET_SKEYS
-----------------------
:Capability: KVM_CAP_S390_SKEYS
:Architectures: s390
:Type: vm ioctl
:Parameters: struct kvm_s390_skeys
:Returns: 0 on success, KVM_S390_GET_SKEYS_NONE if guest is not using storage
keys, negative value on error
This ioctl is used to get guest storage key values on the s390
architecture. The ioctl takes parameters via the kvm_s390_skeys struct::
struct kvm_s390_skeys {
__u64 start_gfn;
__u64 count;
__u64 skeydata_addr;
__u32 flags;
__u32 reserved[9];
};
The start_gfn field is the number of the first guest frame whose storage keys
you want to get.
The count field is the number of consecutive frames (starting from start_gfn)
whose storage keys to get. The count field must be at least 1 and the maximum
allowed value is defined as KVM_S390_SKEYS_MAX. Values outside this range
will cause the ioctl to return -EINVAL.
The skeydata_addr field is the address to a buffer large enough to hold count
bytes. This buffer will be filled with storage key data by the ioctl.
4.91 KVM_S390_SET_SKEYS
4034-4061`KVM_S390_SET_SKEYS`는 같은 s390 capability와 `struct kvm_s390_skeys`를 사용해 guest storage key를 설정합니다.
`start_gfn`에서 시작하는 `count`개 연속 frame이 대상이며 `count`는 1~`KVM_S390_SKEYS_MAX` 범위여야 합니다. 범위 밖이면 `EINVAL`입니다.
`skeydata_addr`는 `count` byte의 storage key를 담은 buffer를 가리키고 각 byte를 대상 frame 하나에 차례로 적용합니다. Architecture상 유효하지 않은 key 값이 하나라도 있으면 `EINVAL`입니다.
4.91 KVM_S390_SET_SKEYS
-----------------------
:Capability: KVM_CAP_S390_SKEYS
:Architectures: s390
:Type: vm ioctl
:Parameters: struct kvm_s390_skeys
:Returns: 0 on success, negative value on error
This ioctl is used to set guest storage key values on the s390
architecture. The ioctl takes parameters via the kvm_s390_skeys struct.
See section on KVM_S390_GET_SKEYS for struct definition.
The start_gfn field is the number of the first guest frame whose storage keys
you want to set.
The count field is the number of consecutive frames (starting from start_gfn)
whose storage keys to get. The count field must be at least 1 and the maximum
allowed value is defined as KVM_S390_SKEYS_MAX. Values outside this range
will cause the ioctl to return -EINVAL.
The skeydata_addr field is the address to a buffer containing count bytes of
storage keys. Each byte in the buffer will be set as the storage key for a
single frame starting at start_gfn for count frames.
Note: If any architecturally invalid key value is found in the given data then
the ioctl will return -EINVAL.
4.92 KVM_S390_IRQ
4062-4121`KVM_S390_IRQ`는 s390 `KVM_CAP_S390_INJECT_IRQ` asynchronous vCPU ioctl입니다. `KVM_S390_INTERRUPT`로 전달할 수 없던 추가 payload를 `struct kvm_s390_irq` union에 담아 guest interrupt를 주입하며 어느 thread에서도 호출할 수 있습니다.
errno조건
`EINVAL`잘못된 type, STOP flag 오류, external-call code가 최대 vCPU 수 초과
`EBUSY`실행 중 vCPU에 SET_PREFIX, STOP이 이미 pending, external call이 이미 pending
Interrupt type·parameter와 pending 상태를 검증합니다.
TypePayload
`KVM_S390_SIGP_STOP``.stop`
`KVM_S390_PROGRAM_INT``.pgm`
`KVM_S390_SIGP_SET_PREFIX``.prefix`
`KVM_S390_RESTART`없음
`KVM_S390_INT_CLOCK_COMP`없음
`KVM_S390_INT_CPU_TIMER`없음
`KVM_S390_INT_EMERGENCY``.emerg`
`KVM_S390_INT_EXTERNAL_CALL``.extcall`
`KVM_S390_MCHK``.mchk`
`type`에 따라 union member를 선택합니다.
Union은 I/O, external, program, emergency, external-call, prefix, stop, machine-check 구조체와 64-byte reserved 공간을 포함합니다.
4.92 KVM_S390_IRQ
-----------------
:Capability: KVM_CAP_S390_INJECT_IRQ
:Architectures: s390
:Type: vcpu ioctl
:Parameters: struct kvm_s390_irq (in)
:Returns: 0 on success, -1 on error
Errors:
====== =================================================================
EINVAL interrupt type is invalid
type is KVM_S390_SIGP_STOP and flag parameter is invalid value,
type is KVM_S390_INT_EXTERNAL_CALL and code is bigger
than the maximum of VCPUs
EBUSY type is KVM_S390_SIGP_SET_PREFIX and vcpu is not stopped,
type is KVM_S390_SIGP_STOP and a stop irq is already pending,
type is KVM_S390_INT_EXTERNAL_CALL and an external call interrupt
is already pending
====== =================================================================
Allows to inject an interrupt to the guest.
Using struct kvm_s390_irq as a parameter allows
to inject additional payload which is not
possible via KVM_S390_INTERRUPT.
Interrupt parameters are passed via kvm_s390_irq::
struct kvm_s390_irq {
__u64 type;
union {
struct kvm_s390_io_info io;
struct kvm_s390_ext_info ext;
struct kvm_s390_pgm_info pgm;
struct kvm_s390_emerg_info emerg;
struct kvm_s390_extcall_info extcall;
struct kvm_s390_prefix_info prefix;
struct kvm_s390_stop_info stop;
struct kvm_s390_mchk_info mchk;
char reserved[64];
} u;
};
type can be one of the following:
- KVM_S390_SIGP_STOP - sigp stop; parameter in .stop
- KVM_S390_PROGRAM_INT - program check; parameters in .pgm
- KVM_S390_SIGP_SET_PREFIX - sigp set prefix; parameters in .prefix
- KVM_S390_RESTART - restart; no parameters
- KVM_S390_INT_CLOCK_COMP - clock comparator interrupt; no parameters
- KVM_S390_INT_CPU_TIMER - CPU timer interrupt; no parameters
- KVM_S390_INT_EMERGENCY - sigp emergency; parameters in .emerg
- KVM_S390_INT_EXTERNAL_CALL - sigp external call; parameters in .extcall
- KVM_S390_MCHK - machine check interrupt; parameters in .mchk
This is an asynchronous vcpu ioctl and can be invoked from any thread.
4.94 KVM_S390_GET_IRQ_STATE
4122-4156`KVM_S390_GET_IRQ_STATE`는 s390 `KVM_CAP_S390_IRQ_STATE` vCPU ioctl로 현재 pending인 모든 interrupt 상태를 한 userspace buffer에 가져옵니다. Migration과 introspection이 주요 용도입니다.
반환의미
>= 0Buffer에 복사한 byte 수
`EINVAL`Buffer size가 0
`ENOBUFS`모든 pending interrupt를 담기에 buffer가 작음; 더 크게 재시도 가능
`EFAULT`잘못된 buffer address
Buffer 유효성과 크기 결과입니다.
`struct kvm_s390_irq_state`는 userspace address `buf`, byte length `len`, `flags`, `reserved[4]`를 담고 pending interrupt마다 `struct kvm_s390_irq` 하나를 buffer에 복사합니다.
Kernel이 과거 `flags == 0`을 검사하지 않았고 QEMU도 flags와 reserved를 미리 0으로 만들지 않았으므로 두 field는 호환성 때문에 앞으로도 사용할 수 없습니다.
4.94 KVM_S390_GET_IRQ_STATE
---------------------------
:Capability: KVM_CAP_S390_IRQ_STATE
:Architectures: s390
:Type: vcpu ioctl
:Parameters: struct kvm_s390_irq_state (out)
:Returns: >= number of bytes copied into buffer,
-EINVAL if buffer size is 0,
-ENOBUFS if buffer size is too small to fit all pending interrupts,
-EFAULT if the buffer address was invalid
This ioctl allows userspace to retrieve the complete state of all currently
pending interrupts in a single buffer. Use cases include migration
and introspection. The parameter structure contains the address of a
userspace buffer and its length::
struct kvm_s390_irq_state {
__u64 buf;
__u32 flags; /* will stay unused for compatibility reasons */
__u32 len;
__u32 reserved[4]; /* will stay unused for compatibility reasons */
};
Userspace passes in the above struct and for each pending interrupt a
struct kvm_s390_irq is copied to the provided buffer.
The structure contains a flags and a reserved field for future extensions. As
the kernel never checked for flags == 0 and QEMU never pre-zeroed flags and
reserved, these fields can not be used in the future without breaking
compatibility.
If -ENOBUFS is returned the buffer provided was too small and userspace
may retry with a bigger buffer.
4.95 KVM_S390_SET_IRQ_STATE
4157-4194`KVM_S390_SET_IRQ_STATE`는 s390 `KVM_CAP_S390_IRQ_STATE` vCPU ioctl로 vCPU에 pending인 CPU-local interrupt 전체 상태를 설정합니다. Migration 후 interrupt state 복원용입니다.
입력 `struct kvm_s390_irq_state`와 flags·reserved 호환성 제한은 GET과 같습니다. `buf`가 가리키는 memory에는 주입할 interrupt마다 `struct kvm_s390_irq` 하나가 들어 있고 하나라도 주입하지 못하면 ioctl 전체를 중단합니다.
반환의미
0성공
`EFAULT`잘못된 buffer address
`EINVAL`유효하지 않은 buffer length
`EBUSY`이미 pending interrupt가 있음
기타실제 `KVM_S390_IRQ` 주입 과정의 오류
입력 buffer와 기존 pending state를 검사합니다.
`len`은 `sizeof(struct kvm_s390_irq)`의 배수이면서 0보다 커야 하고, 가능한 CPU-local pending interrupt 최대치인 `(max_vcpus + 32) * sizeof(struct kvm_s390_irq)`를 넘을 수 없습니다.
4.95 KVM_S390_SET_IRQ_STATE
---------------------------
:Capability: KVM_CAP_S390_IRQ_STATE
:Architectures: s390
:Type: vcpu ioctl
:Parameters: struct kvm_s390_irq_state (in)
:Returns: 0 on success,
-EFAULT if the buffer address was invalid,
-EINVAL for an invalid buffer length (see below),
-EBUSY if there were already interrupts pending,
errors occurring when actually injecting the
interrupt. See KVM_S390_IRQ.
This ioctl allows userspace to set the complete state of all cpu-local
interrupts currently pending for the vcpu. It is intended for restoring
interrupt state after a migration. The input parameter is a userspace buffer
containing a struct kvm_s390_irq_state::
struct kvm_s390_irq_state {
__u64 buf;
__u32 flags; /* will stay unused for compatibility reasons */
__u32 len;
__u32 reserved[4]; /* will stay unused for compatibility reasons */
};
The restrictions for flags and reserved apply as well.
(see KVM_S390_GET_IRQ_STATE)
The userspace memory referenced by buf contains a struct kvm_s390_irq
for each interrupt to be injected into the guest.
If one of the interrupts could not be injected for some reason the
ioctl aborts.
len must be a multiple of sizeof(struct kvm_s390_irq). It must be > 0
and it must not exceed (max_vcpus + 32) * sizeof(struct kvm_s390_irq),
which is the maximum number of possibly pending cpu-local interrupts.
4.96 KVM_SMI
4195-4205`KVM_SMI`는 x86 `KVM_CAP_X86_SMM` vCPU ioctl입니다. Argument 없이 호출 thread의 vCPU에 system-management interrupt(SMI)를 queue하며 성공 시 0을 반환합니다.
4.96 KVM_SMI
------------
:Capability: KVM_CAP_X86_SMM
:Architectures: x86
:Type: vcpu ioctl
:Parameters: none
:Returns: 0 on success, -1 on error
Queues an SMI on the thread's vcpu.
4.97 KVM_X86_SET_MSR_FILTER
4206-4318`KVM_X86_SET_MSR_FILTER`는 x86 `KVM_CAP_X86_MSR_FILTER` VM ioctl로 guest MSR 접근을 허용하거나 거부하는 filter를 설정합니다. 최대 16개 MSR range bitmap을 정의할 수 있습니다.
Field·flag의미
`base`Bitmap이 시작하는 MSR index
`nmsrs`Bitmap이 다루는 MSR 수
`bitmap`1이면 flags의 operation 허용, 0이면 거부
`KVM_MSR_FILTER_READ`Read access를 bitmap으로 filter
`KVM_MSR_FILTER_WRITE`Write access를 bitmap으로 filter
각 range는 `[base, base+nmsrs)`의 MSR index와 허용 bitmap을 정의합니다.
Range의 bitmap bit 0은 해당 read 또는 write를 거부하고 1은 default action과 관계없이 허용합니다. 하나의 range에 READ와 WRITE를 함께 지정할 수 있습니다.
Flag동작
`KVM_MSR_FILTER_DEFAULT_ALLOW`기본적으로 모든 MSR access 허용
`KVM_MSR_FILTER_DEFAULT_DENY`기본적으로 모든 MSR access 거부
어떤 range에도 걸리지 않는 MSR의 처리입니다.
거부된 접근에서 `KVM_CAP_X86_USER_SPACE_MSR`의 `KVM_MSR_EXIT_REASON_FILTER`가 enable되어 있으면 KVM이 userspace로 exit하여 접근을 intercept하게 합니다. Enable되지 않았으면 guest에 `#GP`를 주입합니다.
Userspace filter가 접근을 허용해도 vCPU model에 따라 KVM이 emulate·virtualize하며, 미지원 MSR 또는 architecture 규칙 때문에 최종적으로 `#GP`가 주입될 수 있습니다.
초기 상태는 range가 없는 DEFAULT_ALLOW입니다. 모든 `nmsrs`가 0인 빈 range set으로 호출하면 filtering을 disable합니다. 이때 DEFAULT_DENY는 유효하지 않아 오류입니다.
Instruction 실행의 side effect로 발생하는 MSR 접근은 filter하지 않습니다. Hardware가 RDMSR·WRMSR 밖에서 MSR bitmap을 적용하지 않으므로 KVM도 이를 따릅니다. 예를 들어 RDPID의 `MSR_TSC_AUX`, SYSENTER의 SYSENTER MSR read가 해당합니다.
전용 VMCS field를 통한 VM-Enter·VM-Exit MSR load/store는 filter하지 않습니다. 반면 VMX load/store list를 통한 접근은 filter하며, VM-Enter에서 거부되면 `EXIT_REASON_MSR_LOAD_FAIL` consistency-check VM-Exit, VM-Exit에서 거부되면 VM-Abort를 합성합니다.
x2APIC MSR 접근은 filter할 수 없으며 KVM은 해당 range filter를 조용히 무시합니다.
vCPU 실행 중 filter를 교체하면 race가 있지만 각 vCPU는 이전 또는 새 filter 중 하나를 봅니다. 두 filter에서 설정이 같은 MSR은 deterministic하게 동작합니다.
거부 접근을 userspace에서 intercept하려면 filter를 활성화하기 전에 `KVM_MSR_EXIT_REASON_FILTER`를 enable하고 모든 filter를 비활성화한 뒤까지 유지해야 합니다. 순서를 어기면 userspace exit 대신 guest `#GP`가 생길 수 있습니다.
4.97 KVM_X86_SET_MSR_FILTER
----------------------------
:Capability: KVM_CAP_X86_MSR_FILTER
:Architectures: x86
:Type: vm ioctl
:Parameters: struct kvm_msr_filter
:Returns: 0 on success, < 0 on error
::
struct kvm_msr_filter_range {
#define KVM_MSR_FILTER_READ (1 << 0)
#define KVM_MSR_FILTER_WRITE (1 << 1)
__u32 flags;
__u32 nmsrs; /* number of msrs in bitmap */
__u32 base; /* MSR index the bitmap starts at */
__u8 *bitmap; /* a 1 bit allows the operations in flags, 0 denies */
};
#define KVM_MSR_FILTER_MAX_RANGES 16
struct kvm_msr_filter {
#define KVM_MSR_FILTER_DEFAULT_ALLOW (0 << 0)
#define KVM_MSR_FILTER_DEFAULT_DENY (1 << 0)
__u32 flags;
struct kvm_msr_filter_range ranges[KVM_MSR_FILTER_MAX_RANGES];
};
flags values for ``struct kvm_msr_filter_range``:
``KVM_MSR_FILTER_READ``
Filter read accesses to MSRs using the given bitmap. A 0 in the bitmap
indicates that read accesses should be denied, while a 1 indicates that
a read for a particular MSR should be allowed regardless of the default
filter action.
``KVM_MSR_FILTER_WRITE``
Filter write accesses to MSRs using the given bitmap. A 0 in the bitmap
indicates that write accesses should be denied, while a 1 indicates that
a write for a particular MSR should be allowed regardless of the default
filter action.
flags values for ``struct kvm_msr_filter``:
``KVM_MSR_FILTER_DEFAULT_ALLOW``
If no filter range matches an MSR index that is getting accessed, KVM will
allow accesses to all MSRs by default.
``KVM_MSR_FILTER_DEFAULT_DENY``
If no filter range matches an MSR index that is getting accessed, KVM will
deny accesses to all MSRs by default.
This ioctl allows userspace to define up to 16 bitmaps of MSR ranges to deny
guest MSR accesses that would normally be allowed by KVM. If an MSR is not
covered by a specific range, the "default" filtering behavior applies. Each
bitmap range covers MSRs from [base .. base+nmsrs).
If an MSR access is denied by userspace, the resulting KVM behavior depends on
whether or not KVM_CAP_X86_USER_SPACE_MSR's KVM_MSR_EXIT_REASON_FILTER is
enabled. If KVM_MSR_EXIT_REASON_FILTER is enabled, KVM will exit to userspace
on denied accesses, i.e. userspace effectively intercepts the MSR access. If
KVM_MSR_EXIT_REASON_FILTER is not enabled, KVM will inject a #GP into the guest
on denied accesses. Note, if an MSR access is denied during emulation of MSR
load/stores during VMX transitions, KVM ignores KVM_MSR_EXIT_REASON_FILTER.
See the below warning for full details.
If an MSR access is allowed by userspace, KVM will emulate and/or virtualize
the access in accordance with the vCPU model. Note, KVM may still ultimately
inject a #GP if an access is allowed by userspace, e.g. if KVM doesn't support
the MSR, or to follow architectural behavior for the MSR.
By default, KVM operates in KVM_MSR_FILTER_DEFAULT_ALLOW mode with no MSR range
filters.
Calling this ioctl with an empty set of ranges (all nmsrs == 0) disables MSR
filtering. In that mode, ``KVM_MSR_FILTER_DEFAULT_DENY`` is invalid and causes
an error.
.. warning::
MSR accesses that are side effects of instruction execution (emulated or
native) are not filtered as hardware does not honor MSR bitmaps outside of
RDMSR and WRMSR, and KVM mimics that behavior when emulating instructions
to avoid pointless divergence from hardware. E.g. RDPID reads MSR_TSC_AUX,
SYSENTER reads the SYSENTER MSRs, etc.
MSRs that are loaded/stored via dedicated VMCS fields are not filtered as
part of VM-Enter/VM-Exit emulation.
MSRs that are loaded/store via VMX's load/store lists _are_ filtered as part
of VM-Enter/VM-Exit emulation. If an MSR access is denied on VM-Enter, KVM
synthesizes a consistency check VM-Exit(EXIT_REASON_MSR_LOAD_FAIL). If an
MSR access is denied on VM-Exit, KVM synthesizes a VM-Abort. In short, KVM
extends Intel's architectural list of MSRs that cannot be loaded/saved via
the VM-Enter/VM-Exit MSR list. It is platform owner's responsibility to
to communicate any such restrictions to their end users.
x2APIC MSR accesses cannot be filtered (KVM silently ignores filters that
cover any x2APIC MSRs).
Note, invoking this ioctl while a vCPU is running is inherently racy. However,
KVM does guarantee that vCPUs will see either the previous filter or the new
filter, e.g. MSRs with identical settings in both the old and new filter will
have deterministic behavior.
Similarly, if userspace wishes to intercept on denied accesses,
KVM_MSR_EXIT_REASON_FILTER must be enabled before activating any filters, and
left enabled until after all filters are deactivated. Failure to do so may
result in KVM injecting a #GP instead of exiting to userspace.
4.98 KVM_CREATE_SPAPR_TCE_64
4319-4351`KVM_CREATE_SPAPR_TCE_64`는 PowerPC `KVM_CAP_SPAPR_TCE_64` VM ioctl이며 생성한 TCE table을 조작할 fd를 반환합니다. 32-bit window만 지원하는 `KVM_CREATE_SPAPR_TCE`의 확장입니다.
`struct kvm_create_spapr_tce_64`는 `liobn`, IOMMU `page_shift`, 예약된 `flags`, page 단위 `offset`과 `size`를 담습니다.
목적은 가변 page size를 갖는 더 큰 추가 DMA window입니다. Window size는 64-bit이고 `size`와 bus `offset`은 IOMMU page 수로 표현합니다. 나머지 기능은 기존 TCE API와 동일합니다.
4.98 KVM_CREATE_SPAPR_TCE_64
----------------------------
:Capability: KVM_CAP_SPAPR_TCE_64
:Architectures: powerpc
:Type: vm ioctl
:Parameters: struct kvm_create_spapr_tce_64 (in)
:Returns: file descriptor for manipulating the created TCE table
This is an extension for KVM_CAP_SPAPR_TCE which only supports 32bit
windows, described in 4.62 KVM_CREATE_SPAPR_TCE
This capability uses extended struct in ioctl interface::
/* for KVM_CAP_SPAPR_TCE_64 */
struct kvm_create_spapr_tce_64 {
__u64 liobn;
__u32 page_shift;
__u32 flags;
__u64 offset; /* in pages */
__u64 size; /* in pages */
};
The aim of extension is to support an additional bigger DMA window with
a variable page size.
KVM_CREATE_SPAPR_TCE_64 receives a 64bit window size, an IOMMU page shift and
a bus offset of the corresponding DMA window, @size and @offset are numbers
of IOMMU pages.
@flags are not used at the moment.
The rest of functionality is identical to KVM_CREATE_SPAPR_TCE.
4.99 KVM_REINJECT_CONTROL
4352-4378`KVM_REINJECT_CONTROL`은 x86 `KVM_CAP_REINJECT_CONTROL` VM ioctl로 i8254 PIT interrupt 재주입 방식을 설정합니다. PIT 생성이 선행되지 않으면 `ENXIO`, 입력 구조체를 읽지 못하면 `EFAULT`입니다.
기본 reinject mode는 경과한 PIT tick을 queue하고 i8254가 주입한 vector의 interrupt 완료를 감시합니다. Pending i8254 interrupt가 없을 때 tick 하나를 dequeue하여 interrupt를 주입합니다.
`struct kvm_reinject_control.pit_reinject`가 0인 non-reinject mode는 tick이 도착하자마자 interrupt를 주입합니다. PIT를 timing에 사용하는 Linux 2.4.x 같은 구형 OS가 아니라면 이 mode가 권장됩니다.
4.99 KVM_REINJECT_CONTROL
-------------------------
:Capability: KVM_CAP_REINJECT_CONTROL
:Architectures: x86
:Type: vm ioctl
:Parameters: struct kvm_reinject_control (in)
:Returns: 0 on success,
-EFAULT if struct kvm_reinject_control cannot be read,
-ENXIO if KVM_CREATE_PIT or KVM_CREATE_PIT2 didn't succeed earlier.
i8254 (PIT) has two modes, reinject and !reinject. The default is reinject,
where KVM queues elapsed i8254 ticks and monitors completion of interrupt from
vector(s) that i8254 injects. Reinject mode dequeues a tick and injects its
interrupt whenever there isn't a pending interrupt from i8254.
!reinject mode injects an interrupt as soon as a tick arrives.
::
struct kvm_reinject_control {
__u8 pit_reinject;
__u8 reserved[31];
};
pit_reinject = 0 (!reinject mode) is recommended, unless running an old
operating system that uses the PIT for timing (e.g. Linux 2.4.x).
4.100 KVM_PPC_CONFIGURE_V3_MMU
4379-4412`KVM_PPC_CONFIGURE_V3_MMU`는 PowerPC VM이 radix 또는 HPT translation을 사용할지 정하고 guest process table pointer를 설정합니다. Capability는 `KVM_CAP_PPC_MMU_RADIX` 또는 `KVM_CAP_PPC_MMU_HASH_V3`입니다.
Flag동작
`KVM_PPC_MMUV3_RADIX` setRadix-tree translation
`KVM_PPC_MMUV3_RADIX` clearHashed page-table translation
`KVM_PPC_MMUV3_GTSE` setKVM이 허용하면 global TLB·SLB invalidation instruction 사용
`KVM_PPC_MMUV3_GTSE` clearGlobal invalidation instruction 사용 금지
Translation mode와 global invalidation 권한을 설정합니다.
`process_table`은 guest address space에 있는 process table의 주소와 크기를 지정하며 Power ISA v3.00 Book III의 partition-table entry 두 번째 doubleword 형식입니다. 구조체를 읽지 못하면 `EFAULT`, 구성이 잘못되면 `EINVAL`입니다.
4.100 KVM_PPC_CONFIGURE_V3_MMU
------------------------------
:Capability: KVM_CAP_PPC_MMU_RADIX or KVM_CAP_PPC_MMU_HASH_V3
:Architectures: ppc
:Type: vm ioctl
:Parameters: struct kvm_ppc_mmuv3_cfg (in)
:Returns: 0 on success,
-EFAULT if struct kvm_ppc_mmuv3_cfg cannot be read,
-EINVAL if the configuration is invalid
This ioctl controls whether the guest will use radix or HPT (hashed
page table) translation, and sets the pointer to the process table for
the guest.
::
struct kvm_ppc_mmuv3_cfg {
__u64 flags;
__u64 process_table;
};
There are two bits that can be set in flags; KVM_PPC_MMUV3_RADIX and
KVM_PPC_MMUV3_GTSE. KVM_PPC_MMUV3_RADIX, if set, configures the guest
to use radix tree translation, and if clear, to use HPT translation.
KVM_PPC_MMUV3_GTSE, if set and if KVM permits it, configures the guest
to be able to use the global TLB and SLB invalidation instructions;
if clear, the guest may not use these instructions.
The process_table field specifies the address and size of the guest
process table, which is in the guest's space. This field is formatted
as the second doubleword of the partition table entry, as defined in
the Power ISA V3.00, Book III section 5.7.6.1.
4.101 KVM_PPC_GET_RMMU_INFO
4413-4449`KVM_PPC_GET_RMMU_INFO`는 PowerPC `KVM_CAP_PPC_MMU_RADIX` VM ioctl로 지원 radix-tree geometry와 `tlbie` instruction의 AP(actual page size) field encoding 목록을 반환합니다.
`geometries[8]`의 각 entry는 최소 page size의 base-2 log인 `page_shift`와 PTE level부터 PGD level까지 각 tree level에서 index하는 bit 수 `level_bits[4]`를 담습니다. 사용하지 않는 entry는 `page_shift`가 0입니다.
`ap_encodings[8]`은 상위 3 bit에 AP 값, 하위 6 bit에 page size의 base-2 log를 encode합니다. 출력 구조체를 쓰지 못하면 `EFAULT`, 유용한 정보를 줄 수 없으면 `EINVAL`입니다.
4.101 KVM_PPC_GET_RMMU_INFO
---------------------------
:Capability: KVM_CAP_PPC_MMU_RADIX
:Architectures: ppc
:Type: vm ioctl
:Parameters: struct kvm_ppc_rmmu_info (out)
:Returns: 0 on success,
-EFAULT if struct kvm_ppc_rmmu_info cannot be written,
-EINVAL if no useful information can be returned
This ioctl returns a structure containing two things: (a) a list
containing supported radix tree geometries, and (b) a list that maps
page sizes to put in the "AP" (actual page size) field for the tlbie
(TLB invalidate entry) instruction.
::
struct kvm_ppc_rmmu_info {
struct kvm_ppc_radix_geom {
__u8 page_shift;
__u8 level_bits[4];
__u8 pad[3];
} geometries[8];
__u32 ap_encodings[8];
};
The geometries[] field gives up to 8 supported geometries for the
radix page table, in terms of the log base 2 of the smallest page
size, and the number of bits indexed at each level of the tree, from
the PTE level up to the PGD level in that order. Any unused entries
will have 0 in the page_shift field.
The ap_encodings gives the supported page sizes and their AP field
encodings, encoded with the AP value in the top 3 bits and the log
base 2 of the page size in the bottom 6 bits.
4.102 KVM_PPC_RESIZE_HPT_PREPARE
4450-4503`KVM_PPC_RESIZE_HPT_PREPARE`는 PAPR guest HPT runtime resize의 준비를 시작·취소·감시하며 `H_RESIZE_HPT_PREPARE` hypercall을 구현합니다.
반환의미
0준비 완료 또는 shift 0 취소 완료
> 0준비 진행 상태; 완료까지 예상 millisecond
`EFAULT`입력 구조체를 읽지 못함
`EINVAL`shift 또는 flags 오류
`ENOMEM`새 HPT 할당 실패
Pending HPT 준비 상태를 나타냅니다.
Pending HPT가 없고 `shift > 0`이면 크기 `2^shift` byte의 새 HPT 준비를 시작합니다. 기존 pending HPT의 크기가 다르면 버리고 요청 크기로 다시 시작합니다.
요청 크기와 같은 pending HPT가 있으면 완료 시 0, 실패 시 오류를 반환하고 pending HPT를 버리며, 진행 중이면 예상 남은 millisecond를 반환합니다.
`shift == 0`은 pending HPT를 버리고 진행 중 준비를 취소합니다. `flags`는 예약되어 있어 bit를 하나라도 set하면 `EINVAL`입니다.
보통 같은 parameter로 반복 호출합니다. 첫 호출이 준비를 시작하고 후속 호출이 0 또는 오류가 나올 때까지 상태를 감시합니다.
4.102 KVM_PPC_RESIZE_HPT_PREPARE
--------------------------------
:Capability: KVM_CAP_SPAPR_RESIZE_HPT
:Architectures: powerpc
:Type: vm ioctl
:Parameters: struct kvm_ppc_resize_hpt (in)
:Returns: 0 on successful completion,
>0 if a new HPT is being prepared, the value is an estimated
number of milliseconds until preparation is complete,
-EFAULT if struct kvm_reinject_control cannot be read,
-EINVAL if the supplied shift or flags are invalid,
-ENOMEM if unable to allocate the new HPT,
Used to implement the PAPR extension for runtime resizing of a guest's
Hashed Page Table (HPT). Specifically this starts, stops or monitors
the preparation of a new potential HPT for the guest, essentially
implementing the H_RESIZE_HPT_PREPARE hypercall.
::
struct kvm_ppc_resize_hpt {
__u64 flags;
__u32 shift;
__u32 pad;
};
If called with shift > 0 when there is no pending HPT for the guest,
this begins preparation of a new pending HPT of size 2^(shift) bytes.
It then returns a positive integer with the estimated number of
milliseconds until preparation is complete.
If called when there is a pending HPT whose size does not match that
requested in the parameters, discards the existing pending HPT and
creates a new one as above.
If called when there is a pending HPT of the size requested, will:
* If preparation of the pending HPT is already complete, return 0
* If preparation of the pending HPT has failed, return an error
code, then discard the pending HPT.
* If preparation of the pending HPT is still in progress, return an
estimated number of milliseconds until preparation is complete.
If called with shift == 0, discards any currently pending HPT and
returns 0 (i.e. cancels any in-progress preparation).
flags is reserved for future expansion, currently setting any bits in
flags will result in an -EINVAL.
Normally this will be called repeatedly with the same parameters until
it returns <= 0. The first call will initiate preparation, subsequent
ones will monitor preparation until it completes or fails.
4.103 KVM_PPC_RESIZE_HPT_COMMIT
4504-4548`KVM_PPC_RESIZE_HPT_COMMIT`은 준비한 새 HPT로 guest를 전환하며 `H_RESIZE_HPT_COMMIT` hypercall을 구현합니다. 동일 parameter의 PREPARE가 0을 반환한 뒤에만 호출해야 합니다.
errno의미
`EFAULT`입력 구조체를 읽지 못함
`EINVAL`shift 또는 flags 오류
`ENXIO`Pending HPT가 없거나 크기 불일치
`EBUSY`Pending HPT 준비 미완료
`ENOSPC`기존 entry 이동 중 hash collision
`EIO`기타 오류
Prepared table과 전환 조건을 검증합니다.
Guest가 모든 vCPU의 MMU-enabled memory access를 멈춘 quiescent state에 들어가지 않았다면 결과가 정의되지 않습니다.
성공하면 pending HPT가 active HPT가 되고 이전 HPT는 폐기됩니다. 실패하면 guest는 이전 HPT로 계속 동작합니다.
4.103 KVM_PPC_RESIZE_HPT_COMMIT
-------------------------------
:Capability: KVM_CAP_SPAPR_RESIZE_HPT
:Architectures: powerpc
:Type: vm ioctl
:Parameters: struct kvm_ppc_resize_hpt (in)
:Returns: 0 on successful completion,
-EFAULT if struct kvm_reinject_control cannot be read,
-EINVAL if the supplied shift or flags are invalid,
-ENXIO is there is no pending HPT, or the pending HPT doesn't
have the requested size,
-EBUSY if the pending HPT is not fully prepared,
-ENOSPC if there was a hash collision when moving existing
HPT entries to the new HPT,
-EIO on other error conditions
Used to implement the PAPR extension for runtime resizing of a guest's
Hashed Page Table (HPT). Specifically this requests that the guest be
transferred to working with the new HPT, essentially implementing the
H_RESIZE_HPT_COMMIT hypercall.
::
struct kvm_ppc_resize_hpt {
__u64 flags;
__u32 shift;
__u32 pad;
};
This should only be called after KVM_PPC_RESIZE_HPT_PREPARE has
returned 0 with the same parameters. In other cases
KVM_PPC_RESIZE_HPT_COMMIT will return an error (usually -ENXIO or
-EBUSY, though others may be possible if the preparation was started,
but failed).
This will have undefined effects on the guest if it has not already
placed itself in a quiescent state where no vcpu will make MMU enabled
memory accesses.
On successful completion, the pending HPT will become the guest's active
HPT and the previous HPT will be discarded.
On failure, the guest will still be operating on its previous HPT.
4.104 KVM_X86_GET_MCE_CAP_SUPPORTED
4549-4561`KVM_X86_GET_MCE_CAP_SUPPORTED`는 x86 `KVM_CAP_MCE` system ioctl로 지원 machine-check capability를 64-bit `mce_cap`에 반환합니다. 형식은 `MSR_IA32_MCG_CAP`과 같고 지원 bit가 set됩니다.
4.104 KVM_X86_GET_MCE_CAP_SUPPORTED
-----------------------------------
:Capability: KVM_CAP_MCE
:Architectures: x86
:Type: system ioctl
:Parameters: u64 mce_cap (out)
:Returns: 0 on success, -1 on error
Returns supported MCE capabilities. The u64 mce_cap parameter
has the same format as the MSR_IA32_MCG_CAP register. Supported
capabilities will have the corresponding bits set.
4.105 KVM_X86_SETUP_MCE
4562-4580`KVM_X86_SETUP_MCE`는 x86 vCPU의 machine-check support를 초기화합니다. 입력 `mcg_cap`은 `MSR_IA32_MCG_CAP` 형식이며 enable할 capability를 지정합니다.
최대 error-reporting bank 수는 `KVM_CAP_MCE` 조회에서 얻고 지원 capability는 `KVM_X86_GET_MCE_CAP_SUPPORTED`로 얻습니다. Bank 수가 잘못됐거나 미지원 capability를 요청하면 `EINVAL`, 값을 읽지 못하면 `EFAULT`입니다.
4.105 KVM_X86_SETUP_MCE
-----------------------
:Capability: KVM_CAP_MCE
:Architectures: x86
:Type: vcpu ioctl
:Parameters: u64 mcg_cap (in)
:Returns: 0 on success,
-EFAULT if u64 mcg_cap cannot be read,
-EINVAL if the requested number of banks is invalid,
-EINVAL if requested MCE capability is not supported.
Initializes MCE support for use. The u64 mcg_cap parameter
has the same format as the MSR_IA32_MCG_CAP register and
specifies which capabilities should be enabled. The maximum
supported number of error-reporting banks can be retrieved when
checking for KVM_CAP_MCE. The supported capabilities can be
retrieved with KVM_X86_GET_MCE_CAP_SUPPORTED.
4.106 KVM_X86_SET_MCE
4581-4614`KVM_X86_SET_MCE`는 `struct kvm_x86_mce`로 x86 guest에 machine-check error를 주입합니다. `status`, `addr`, `misc`, `mcg_status`, `bank`를 전달합니다.
Bank 번호가 잘못됐거나 `status`의 VAL bit가 set되지 않으면 `EINVAL`, 구조체를 읽지 못하면 `EFAULT`입니다.
Uncorrected error는 MCE exception으로 주입합니다. Guest `MCG_STATUS`가 MCE 진행 중임을 나타내면 KVM은 `KVM_EXIT_SHUTDOWN` VM exit를 일으킵니다.
Corrected error는 해당 bank가 이전 uncorrected error를 보유하지 않은 경우 bank에 저장만 합니다.
4.106 KVM_X86_SET_MCE
---------------------
:Capability: KVM_CAP_MCE
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_x86_mce (in)
:Returns: 0 on success,
-EFAULT if struct kvm_x86_mce cannot be read,
-EINVAL if the bank number is invalid,
-EINVAL if VAL bit is not set in status field.
Inject a machine check error (MCE) into the guest. The input
parameter is::
struct kvm_x86_mce {
__u64 status;
__u64 addr;
__u64 misc;
__u64 mcg_status;
__u8 bank;
__u8 pad1[7];
__u64 pad2[3];
};
If the MCE being reported is an uncorrected error, KVM will
inject it as an MCE exception into the guest. If the guest
MCG_STATUS register reports that an MCE is in progress, KVM
causes an KVM_EXIT_SHUTDOWN vmexit.
Otherwise, if the MCE is a corrected error, KVM will just
store it in the corresponding bank (provided this bank is
not holding a previously reported uncorrected error).
4.107 KVM_S390_GET_CMMA_BITS
4615-4715`KVM_S390_GET_CMMA_BITS`는 s390 `KVM_CAP_S390_CMMA_MIGRATION` VM ioctl로 CMMA bit 값을 가져옵니다. Live migration 저장 또는 `KVM_S390_CMMA_PEEK`을 통한 비파괴 조회에 사용합니다.
errno조건
`ENOMEM`작업용 memory 할당 실패
`ENXIO`CMMA가 enable되지 않음
`EINVAL`PEEK 없이 migration mode 미활성 또는 dirty tracking 중지
`EFAULT`잘못된 userspace address 또는 page table 없음; 예: hugepage
CMMA·migration mode와 userspace mapping을 검사합니다.
Live migration 사용 시 VM property `KVM_REQ_START_MIGRATION`으로 migration mode를 enable해야 합니다. PEEK mode는 migration mode 밖에서도 기존 storage attribute를 읽고 다른 state를 바꾸지 않습니다.
Field의미
`start_gfn`조회 시작 guest frame
`count`Buffer byte 수; 최대 `KVM_S390_SKEYS_MAX`로 clamp
`flags`현재 `KVM_S390_CMMA_PEEK`
`remaining`남아 있는 dirty CMMA 값 수
`mask`GET에서는 미사용
`values`결과 userspace buffer pointer
CMMA 값 하나는 1 byte입니다.
기본 migration mode에서는 clean page를 건너뛰므로 출력 `start_gfn`이 첫 dirty CMMA frame으로 바뀔 수 있습니다. 출력 `count`는 실제 기록 byte 수이며 16 byte의 연속 clean 값을 만나면 buffer 채우기를 멈춥니다.
CMMA migration block header가 address와 length를 합쳐 16 byte이므로 뒤에 dirty data가 있다면 clean 구간이 header보다 크지 않을 때 일부 clean data도 돌려보냅니다. 전송량을 줄이는 대신 userspace 왕복이 늘며 다음 호출은 clean 값을 건너뜁니다.
PEEK mode에서는 출력 start_gfn이 입력과 같고 count도 memory 끝에 닿지 않는 한 입력과 같습니다. 두 mode 모두 `remaining`은 남은 dirty CMMA 수이며, PEEK인데 migration mode가 아니면 0입니다.
4.107 KVM_S390_GET_CMMA_BITS
----------------------------
:Capability: KVM_CAP_S390_CMMA_MIGRATION
:Architectures: s390
:Type: vm ioctl
:Parameters: struct kvm_s390_cmma_log (in, out)
:Returns: 0 on success, a negative value on error
Errors:
====== =============================================================
ENOMEM not enough memory can be allocated to complete the task
ENXIO if CMMA is not enabled
EINVAL if KVM_S390_CMMA_PEEK is not set but migration mode was not enabled
EINVAL if KVM_S390_CMMA_PEEK is not set but dirty tracking has been
disabled (and thus migration mode was automatically disabled)
EFAULT if the userspace address is invalid or if no page table is
present for the addresses (e.g. when using hugepages).
====== =============================================================
This ioctl is used to get the values of the CMMA bits on the s390
architecture. It is meant to be used in two scenarios:
- During live migration to save the CMMA values. Live migration needs
to be enabled via the KVM_REQ_START_MIGRATION VM property.
- To non-destructively peek at the CMMA values, with the flag
KVM_S390_CMMA_PEEK set.
The ioctl takes parameters via the kvm_s390_cmma_log struct. The desired
values are written to a buffer whose location is indicated via the "values"
member in the kvm_s390_cmma_log struct. The values in the input struct are
also updated as needed.
Each CMMA value takes up one byte.
::
struct kvm_s390_cmma_log {
__u64 start_gfn;
__u32 count;
__u32 flags;
union {
__u64 remaining;
__u64 mask;
};
__u64 values;
};
start_gfn is the number of the first guest frame whose CMMA values are
to be retrieved,
count is the length of the buffer in bytes,
values points to the buffer where the result will be written to.
If count is greater than KVM_S390_SKEYS_MAX, then it is considered to be
KVM_S390_SKEYS_MAX. KVM_S390_SKEYS_MAX is re-used for consistency with
other ioctls.
The result is written in the buffer pointed to by the field values, and
the values of the input parameter are updated as follows.
Depending on the flags, different actions are performed. The only
supported flag so far is KVM_S390_CMMA_PEEK.
The default behaviour if KVM_S390_CMMA_PEEK is not set is:
start_gfn will indicate the first page frame whose CMMA bits were dirty.
It is not necessarily the same as the one passed as input, as clean pages
are skipped.
count will indicate the number of bytes actually written in the buffer.
It can (and very often will) be smaller than the input value, since the
buffer is only filled until 16 bytes of clean values are found (which
are then not copied in the buffer). Since a CMMA migration block needs
the base address and the length, for a total of 16 bytes, we will send
back some clean data if there is some dirty data afterwards, as long as
the size of the clean data does not exceed the size of the header. This
allows to minimize the amount of data to be saved or transferred over
the network at the expense of more roundtrips to userspace. The next
invocation of the ioctl will skip over all the clean values, saving
potentially more than just the 16 bytes we found.
If KVM_S390_CMMA_PEEK is set:
the existing storage attributes are read even when not in migration
mode, and no other action is performed;
the output start_gfn will be equal to the input start_gfn,
the output count will be equal to the input count, except if the end of
memory has been reached.
In both cases:
the field "remaining" will indicate the total number of dirty CMMA values
still remaining, or 0 if KVM_S390_CMMA_PEEK is set and migration mode is
not enabled.
mask is unused.
values points to the userspace buffer where the result will be stored.
4.108 KVM_S390_SET_CMMA_BITS
4716-4763`KVM_S390_SET_CMMA_BITS`는 s390 CMMA 값을 설정하며 주로 live migration 복원에 쓰지만 사용 자체에 migration 제한은 없습니다. 각 CMMA 값은 1 byte입니다.
`start_gfn`은 시작 frame, `count`는 buffer에서 고려할 값 수, `values`는 userspace buffer를 가리킵니다. `flags`는 미사용이므로 반드시 0, `mask`는 적용할 PGSTE bit를 지정하며 `remaining`은 미사용입니다.
errno조건
`ENOMEM`작업용 memory 할당 실패
`ENXIO`CMMA 미활성
`EINVAL`count가 `KVM_S390_CMMA_SIZE_MAX` 초과 또는 flags가 0 아님
`EFAULT`잘못된 address·page, memory 끝 이후, page table 없음
입력 크기·주소와 CMMA 상태를 검사합니다.
4.108 KVM_S390_SET_CMMA_BITS
----------------------------
:Capability: KVM_CAP_S390_CMMA_MIGRATION
:Architectures: s390
:Type: vm ioctl
:Parameters: struct kvm_s390_cmma_log (in)
:Returns: 0 on success, a negative value on error
This ioctl is used to set the values of the CMMA bits on the s390
architecture. It is meant to be used during live migration to restore
the CMMA values, but there are no restrictions on its use.
The ioctl takes parameters via the kvm_s390_cmma_values struct.
Each CMMA value takes up one byte.
::
struct kvm_s390_cmma_log {
__u64 start_gfn;
__u32 count;
__u32 flags;
union {
__u64 remaining;
__u64 mask;
};
__u64 values;
};
start_gfn indicates the starting guest frame number,
count indicates how many values are to be considered in the buffer,
flags is not used and must be 0.
mask indicates which PGSTE bits are to be considered.
remaining is not used.
values points to the buffer in userspace where to store the values.
This ioctl can fail with -ENOMEM if not enough memory can be allocated to
complete the task, with -ENXIO if CMMA is not enabled, with -EINVAL if
the count field is too large (e.g. more than KVM_S390_CMMA_SIZE_MAX) or
if the flags field was not 0, with -EFAULT if the userspace address is
invalid, if invalid pages are written to (e.g. after the end of memory)
or if no page table is present for the addresses (e.g. when using
hugepages).
4.109 KVM_PPC_GET_CPU_CHAR
4764-4810`KVM_PPC_GET_CPU_CHAR`는 PowerPC CPU의 speculative execution과 정보 누출 관련 특성 및 권장 software 동작을 반환합니다. CVE-2017-5715, CVE-2017-5753, CVE-2017-5754와 관련됩니다.
Field의미
`character`CPU hardware characteristic
`behaviour`권장 software mitigation 동작
`character_mask`character의 유효 bit
`behaviour_mask`behaviour의 유효 bit
Mask는 kernel이 실제로 채운 유효 bit를 알려 향후 확장을 구분하게 합니다.
`character`는 L1 data cache flash-invalidate instruction 제공 여부, cache entry의 thread-local 사용 mode, `bcctr[l]`의 speculation 방지 여부, speculation barrier instruction 제공 여부를 설명합니다.
`behaviour`는 kernel에서 user mode로 돌아갈 때 L1 data cache를 flush해야 하는지, array bounds check와 array access 사이에 speculation barrier가 필요한지 설명합니다.
Bit 정의는 `H_GET_CPU_CHARACTERISTICS` hypercall과 같습니다.
4.109 KVM_PPC_GET_CPU_CHAR
--------------------------
:Capability: KVM_CAP_PPC_GET_CPU_CHAR
:Architectures: powerpc
:Type: vm ioctl
:Parameters: struct kvm_ppc_cpu_char (out)
:Returns: 0 on successful completion,
-EFAULT if struct kvm_ppc_cpu_char cannot be written
This ioctl gives userspace information about certain characteristics
of the CPU relating to speculative execution of instructions and
possible information leakage resulting from speculative execution (see
CVE-2017-5715, CVE-2017-5753 and CVE-2017-5754). The information is
returned in struct kvm_ppc_cpu_char, which looks like this::
struct kvm_ppc_cpu_char {
__u64 character; /* characteristics of the CPU */
__u64 behaviour; /* recommended software behaviour */
__u64 character_mask; /* valid bits in character */
__u64 behaviour_mask; /* valid bits in behaviour */
};
For extensibility, the character_mask and behaviour_mask fields
indicate which bits of character and behaviour have been filled in by
the kernel. If the set of defined bits is extended in future then
userspace will be able to tell whether it is running on a kernel that
knows about the new bits.
The character field describes attributes of the CPU which can help
with preventing inadvertent information disclosure - specifically,
whether there is an instruction to flash-invalidate the L1 data cache
(ori 30,30,0 or mtspr SPRN_TRIG2,rN), whether the L1 data cache is set
to a mode where entries can only be used by the thread that created
them, whether the bcctr[l] instruction prevents speculation, and
whether a speculation barrier instruction (ori 31,31,0) is provided.
The behaviour field describes actions that software should take to
prevent inadvertent information disclosure, and thus describes which
vulnerabilities the hardware is subject to; specifically whether the
L1 data cache should be flushed when returning to user mode from the
kernel, and whether a speculation barrier should be placed between an
array bounds check and the array access.
These fields use the same bit definitions as the new
H_GET_CPU_CHARACTERISTICS hypercall.
4.110 KVM_MEMORY_ENCRYPT_OP
4811-4829`KVM_MEMORY_ENCRYPT_OP`은 encrypted VM을 지원하는 x86 platform의 VM·vCPU ioctl로 opaque platform-specific 구조체를 통해 memory-encryption command를 실행합니다.
현재 AMD Secure Encrypted Virtualization(SEV) command와 Intel Trusted Domain Extensions(TDX) command에 사용합니다. 세부 command는 `Documentation/virt/kvm/x86/amd-memory-encryption.rst`와 `Documentation/virt/kvm/x86/intel-tdx.rst`가 정의합니다.
4.110 KVM_MEMORY_ENCRYPT_OP
---------------------------
:Capability: basic
:Architectures: x86
:Type: vm ioctl, vcpu ioctl
:Parameters: an opaque platform specific structure (in/out)
:Returns: 0 on success; -1 on error
If the platform supports creating encrypted VMs then this ioctl can be used
for issuing platform-specific memory encryption commands to manage those
encrypted VMs.
Currently, this ioctl is used for issuing both Secure Encrypted Virtualization
(SEV) commands on AMD Processors and Trusted Domain Extensions (TDX) commands
on Intel Processors. The detailed commands are defined in
Documentation/virt/kvm/x86/amd-memory-encryption.rst and
Documentation/virt/kvm/x86/intel-tdx.rst.
4.111 KVM_MEMORY_ENCRYPT_REG_REGION
4830-4853`KVM_MEMORY_ENCRYPT_REG_REGION`은 x86 SEV guest에서 encrypted data를 담을 수 있는 guest RAM·SMRAM 같은 memory region을 `struct kvm_enc_region`으로 등록합니다.
SEV encryption tweak 때문에 위치가 다른 동일 plaintext page는 서로 다른 ciphertext가 됩니다. 따라서 ciphertext page를 단순 swap·move해도 plaintext가 같이 이동하지 않아 physical backing page relocation이나 migration에는 추가 단계가 필요합니다.
현재 SEV key-management specification에는 ciphertext page swap·migration command가 없으므로 등록한 guest memory region을 당분간 pin합니다.
4.111 KVM_MEMORY_ENCRYPT_REG_REGION
-----------------------------------
:Capability: basic
:Architectures: x86
:Type: system
:Parameters: struct kvm_enc_region (in)
:Returns: 0 on success; -1 on error
This ioctl can be used to register a guest memory region which may
contain encrypted data (e.g. guest RAM, SMRAM etc).
It is used in the SEV-enabled guest. When encryption is enabled, a guest
memory region may contain encrypted data. The SEV memory encryption
engine uses a tweak such that two identical plaintext pages, each at
different locations will have differing ciphertexts. So swapping or
moving ciphertext of those pages will not result in plaintext being
swapped. So relocating (or migrating) physical backing pages for the SEV
guest will require some additional steps.
Note: The current SEV key management spec does not provide commands to
swap or migrate (move) ciphertext pages. Hence, for now we pin the guest
memory region registered with the ioctl.
4.112 KVM_MEMORY_ENCRYPT_UNREG_REGION
4854-4865`KVM_MEMORY_ENCRYPT_UNREG_REGION`은 앞서 `KVM_MEMORY_ENCRYPT_REG_REGION`으로 등록한 x86 encrypted guest memory region을 해제합니다.
4.112 KVM_MEMORY_ENCRYPT_UNREG_REGION
-------------------------------------
:Capability: basic
:Architectures: x86
:Type: system
:Parameters: struct kvm_enc_region (in)
:Returns: 0 on success; -1 on error
This ioctl can be used to unregister the guest memory region registered
with KVM_MEMORY_ENCRYPT_REG_REGION ioctl above.
4.113 KVM_HYPERV_EVENTFD
4866-4900`KVM_HYPERV_EVENTFD`는 x86 `KVM_CAP_HYPERV_EVENTFD` VM ioctl로 Hyper-V connection ID의 `SIGNAL_EVENT` hypercall notification을 받을 eventfd를 등록하거나 해제합니다. 정상 notification은 userspace exit 없이 전달됩니다.
Event flag number인 bit 24:31이 0이 아닌 SIGNAL_EVENT hypercall은 여전히 `KVM_EXIT_HYPERV_HCALL` userspace exit를 일으킵니다.
`struct kvm_hyperv_eventfd`는 24 bit에 들어가야 하는 `conn_id`, eventfd `fd`, `flags`와 padding을 담습니다. `KVM_HYPERV_EVENTFD_DEASSIGN`은 등록 해제를 뜻합니다.
반환의미
0성공
`EINVAL`conn_id 또는 flags가 허용 범위 밖
`ENOENT`등록되지 않은 conn_id 해제
`EEXIST`이미 등록된 conn_id를 다시 등록
Connection ID와 등록 상태 오류를 구분합니다.
4.113 KVM_HYPERV_EVENTFD
------------------------
:Capability: KVM_CAP_HYPERV_EVENTFD
:Architectures: x86
:Type: vm ioctl
:Parameters: struct kvm_hyperv_eventfd (in)
This ioctl (un)registers an eventfd to receive notifications from the guest on
the specified Hyper-V connection id through the SIGNAL_EVENT hypercall, without
causing a user exit. SIGNAL_EVENT hypercall with non-zero event flag number
(bits 24-31) still triggers a KVM_EXIT_HYPERV_HCALL user exit.
::
struct kvm_hyperv_eventfd {
__u32 conn_id;
__s32 fd;
__u32 flags;
__u32 padding[3];
};
The conn_id field should fit within 24 bits::
#define KVM_HYPERV_CONN_ID_MASK 0x00ffffff
The acceptable values for the flags field are::
#define KVM_HYPERV_EVENTFD_DEASSIGN (1 << 0)
:Returns: 0 on success,
-EINVAL if conn_id or flags is outside the allowed range,
-ENOENT on deassign if the conn_id isn't registered,
-EEXIST on assign if the conn_id is already registered
4.114 KVM_GET_NESTED_STATE
4901-4974`KVM_GET_NESTED_STATE`는 x86 `KVM_CAP_NESTED_STATE` vCPU ioctl로 kernel의 nested-virtualization state를 userspace로 복사합니다. 필요한 최대 state 크기는 `KVM_CHECK_EXTENSION(KVM_CAP_NESTED_STATE)`로 조회합니다.
Userspace가 지정한 `size`보다 전체 state가 크면 `E2BIG`을 반환하고 필요한 크기를 `size`에 기록합니다.
Field의미
`flags`Guest mode, run pending, enlightened VMCS 상태
`format``KVM_STATE_NESTED_FORMAT_VMX` 또는 `_SVM`
`size`Header와 가변 data를 포함한 전체 크기
`hdr`128-byte로 padding된 VMX·SVM header
`data`형식별 가변 state
VMX와 SVM 형식을 하나의 migration 구조체로 전달합니다.
공통 flag는 `KVM_STATE_NESTED_GUEST_MODE`, `KVM_STATE_NESTED_RUN_PENDING`, `KVM_STATE_NESTED_EVMCS`입니다.
VMX header는 `vmxon_pa`, `vmcs12_pa`, SMM guest-mode·VMXON flag, preemption-timer deadline flag와 deadline을 담습니다. VMX data에는 각각 4KiB인 `vmcs12`와 `shadow_vmcs12`가 들어갑니다.
4.114 KVM_GET_NESTED_STATE
--------------------------
:Capability: KVM_CAP_NESTED_STATE
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_nested_state (in/out)
:Returns: 0 on success, -1 on error
Errors:
===== =============================================================
E2BIG the total state size exceeds the value of 'size' specified by
the user; the size required will be written into size.
===== =============================================================
::
struct kvm_nested_state {
__u16 flags;
__u16 format;
__u32 size;
union {
struct kvm_vmx_nested_state_hdr vmx;
struct kvm_svm_nested_state_hdr svm;
/* Pad the header to 128 bytes. */
__u8 pad[120];
} hdr;
union {
struct kvm_vmx_nested_state_data vmx[0];
struct kvm_svm_nested_state_data svm[0];
} data;
};
#define KVM_STATE_NESTED_GUEST_MODE 0x00000001
#define KVM_STATE_NESTED_RUN_PENDING 0x00000002
#define KVM_STATE_NESTED_EVMCS 0x00000004
#define KVM_STATE_NESTED_FORMAT_VMX 0
#define KVM_STATE_NESTED_FORMAT_SVM 1
#define KVM_STATE_NESTED_VMX_VMCS_SIZE 0x1000
#define KVM_STATE_NESTED_VMX_SMM_GUEST_MODE 0x00000001
#define KVM_STATE_NESTED_VMX_SMM_VMXON 0x00000002
#define KVM_STATE_VMX_PREEMPTION_TIMER_DEADLINE 0x00000001
struct kvm_vmx_nested_state_hdr {
__u64 vmxon_pa;
__u64 vmcs12_pa;
struct {
__u16 flags;
} smm;
__u32 flags;
__u64 preemption_timer_deadline;
};
struct kvm_vmx_nested_state_data {
__u8 vmcs12[KVM_STATE_NESTED_VMX_VMCS_SIZE];
__u8 shadow_vmcs12[KVM_STATE_NESTED_VMX_VMCS_SIZE];
};
This ioctl copies the vcpu's nested virtualization state from the kernel to
userspace.
The maximum size of the state can be retrieved by passing KVM_CAP_NESTED_STATE
to the KVM_CHECK_EXTENSION ioctl().
4.115 KVM_SET_NESTED_STATE
4975-4986`KVM_SET_NESTED_STATE`는 x86 nested state를 userspace의 `struct kvm_nested_state`에서 kernel vCPU로 복원합니다. 구조체와 flag 정의는 `KVM_GET_NESTED_STATE`와 같습니다.
4.115 KVM_SET_NESTED_STATE
--------------------------
:Capability: KVM_CAP_NESTED_STATE
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_nested_state (in)
:Returns: 0 on success, -1 on error
This copies the vcpu's kvm_nested_state struct from userspace to the kernel.
For the definition of struct kvm_nested_state, see KVM_GET_NESTED_STATE.
4.116 KVM_(UN)REGISTER_COALESCED_MMIO
4987-5015Coalesced I/O 등록·해제 ioctl은 모든 architecture의 VM ioctl입니다. MMIO는 `KVM_CAP_COALESCED_MMIO`, PIO는 `KVM_CAP_COALESCED_PIO`를 사용하고 `struct kvm_coalesced_mmio_zone`으로 범위를 지정합니다.
빈번한 hardware-register write emulation을 미뤄 userspace exit를 줄이는 최적화입니다. 등록된 register write는 즉시 exit하지 않고 kernel·userspace 공유 ring buffer에 기록됩니다.
같은 device의 다른 register read 또는 write처럼 더 미룰 수 없는 접근이 vmexit를 만들면 userspace가 먼저 ring-buffer write를 처리한 뒤 마지막 접근을 emulate합니다.
Coalesced PIO는 MMIO와 같은 방식이지만 memory address 대신 I/O port 접근을 기록합니다.
4.116 KVM_(UN)REGISTER_COALESCED_MMIO
-------------------------------------
:Capability: KVM_CAP_COALESCED_MMIO (for coalesced mmio)
KVM_CAP_COALESCED_PIO (for coalesced pio)
:Architectures: all
:Type: vm ioctl
:Parameters: struct kvm_coalesced_mmio_zone
:Returns: 0 on success, < 0 on error
Coalesced I/O is a performance optimization that defers hardware
register write emulation so that userspace exits are avoided. It is
typically used to reduce the overhead of emulating frequently accessed
hardware registers.
When a hardware register is configured for coalesced I/O, write accesses
do not exit to userspace and their value is recorded in a ring buffer
that is shared between kernel and userspace.
Coalesced I/O is used if one or more write accesses to a hardware
register can be deferred until a read or a write to another hardware
register on the same device. This last access will cause a vmexit and
userspace will process accesses from the ring buffer before emulating
it. That will avoid exiting to userspace on repeated writes.
Coalesced pio is based on coalesced mmio. There is little difference
between coalesced mmio and pio except that coalesced pio records accesses
to I/O ports.
4.117 KVM_CLEAR_DIRTY_LOG
5016-5057`KVM_CLEAR_DIRTY_LOG`는 x86·arm64·MIPS의 `KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2` VM ioctl로 memory slot page의 dirty 상태를 입력 bitmap에 따라 clear합니다.
Field의미
`slot`Memory slot; multi-address-space이면 bit 16:31에 address-space ID
`first_page`처음 대상 page, 64의 배수
`num_pages`Bitmap bit 수; 보통 64의 배수
`dirty_bitmap`Page마다 1 bit인 userspace 입력 bitmap
Bitmap bit 0은 slot의 `first_page`에 대응합니다.
`num_pages`도 64의 배수여야 하지만 `first_page + num_pages`가 slot 끝과 같다면 마지막 구간은 예외입니다.
입력 bitmap에서 set된 bit의 page를 KVM dirty bitmap에서 clean으로 표시하고, write-protection 또는 page-table dirty bit clear 같은 방식으로 그 page의 dirty tracking을 다시 enable합니다.
주 용도는 manual dirty-log protection이 enable된 경우지만, `KVM_CHECK_EXTENSION`이 capability 존재를 확인하면 언제든 호출할 수 있습니다.
4.117 KVM_CLEAR_DIRTY_LOG
-------------------------
:Capability: KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2
:Architectures: x86, arm64, mips
:Type: vm ioctl
:Parameters: struct kvm_clear_dirty_log (in)
:Returns: 0 on success, -1 on error
::
/* for KVM_CLEAR_DIRTY_LOG */
struct kvm_clear_dirty_log {
__u32 slot;
__u32 num_pages;
__u64 first_page;
union {
void __user *dirty_bitmap; /* one bit per page */
__u64 padding;
};
};
The ioctl clears the dirty status of pages in a memory slot, according to
the bitmap that is passed in struct kvm_clear_dirty_log's dirty_bitmap
field. Bit 0 of the bitmap corresponds to page "first_page" in the
memory slot, and num_pages is the size in bits of the input bitmap.
first_page must be a multiple of 64; num_pages must also be a multiple of
64 unless first_page + num_pages is the size of the memory slot. For each
bit that is set in the input bitmap, the corresponding page is marked "clean"
in KVM's dirty bitmap, and dirty tracking is re-enabled for that page
(for example via write-protection, or by clearing the dirty bit in
a page table entry).
If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 of slot field specifies
the address space for which you want to clear the dirty status. See
KVM_SET_USER_MEMORY_REGION for details on the usage of slot field.
This ioctl is mostly useful when KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2
is enabled; for more information, see the description of the capability.
However, it can always be used as long as KVM_CHECK_EXTENSION confirms
that KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 is present.
4.118 KVM_GET_SUPPORTED_HV_CPUID
5058-5128`KVM_GET_SUPPORTED_HV_CPUID`는 KVM Hyper-V emulation 관련 x86 CPUID leaf를 반환합니다. System ioctl은 `KVM_CAP_SYS_HYPERV_CPUID`, deprecated vCPU ioctl은 `KVM_CAP_HYPERV_CPUID`를 사용합니다.
Windows·Hyper-V guest에 제시할 Hyper-V enlightenment CPUID를 구성하는 데 쓰입니다. TLFS가 정의한 leaf 일부가 KVM feature leaf `0x40000000`·`0x40000001`과 겹치므로 `KVM_GET_SUPPORTED_CPUID`로는 얻을 수 없습니다.
분류Leaf
기본VENDOR_AND_MAX_FUNCTIONS, INTERFACE, VERSION
기능FEATURES, ENLIGHTMENT_INFO, IMPLEMENT_LIMITS, NESTED_FEATURES
Synthetic debuggerSYNDBG_VENDOR_AND_MAX_FUNCTIONS, SYNDBG_INTERFACE, SYNDBG_PLATFORM_CAPABILITIES
Vendor·interface부터 nested·synthetic debugger 정보를 포함합니다.
`kvm_cpuid2.nent`가 leaf 수보다 작으면 `E2BIG`입니다. 충분하면 실제 entry 수로 `nent`를 갱신하고 배열을 채웁니다. Entry의 `index`와 `flags`는 현재 reserved이므로 특정 값을 기대하면 안 됩니다.
System ioctl은 지원 bit를 무조건 모두 노출합니다. vCPU variant는 Enlightened VMCS를 먼저 enable한 vCPU에만 nested leaf와 `HV_X64_ENLIGHTENED_VMCS_RECOMMENDED`를 보이고, kernel LAPIC이 있을 때만 `HV_STIMER_DIRECT_MODE_AVAILABLE`을 노출하는 제약 때문에 deprecated입니다.
4.118 KVM_GET_SUPPORTED_HV_CPUID
--------------------------------
:Capability: KVM_CAP_HYPERV_CPUID (vcpu), KVM_CAP_SYS_HYPERV_CPUID (system)
:Architectures: x86
:Type: system ioctl, vcpu ioctl
:Parameters: struct kvm_cpuid2 (in/out)
:Returns: 0 on success, -1 on error
::
struct kvm_cpuid2 {
__u32 nent;
__u32 padding;
struct kvm_cpuid_entry2 entries[0];
};
struct kvm_cpuid_entry2 {
__u32 function;
__u32 index;
__u32 flags;
__u32 eax;
__u32 ebx;
__u32 ecx;
__u32 edx;
__u32 padding[3];
};
This ioctl returns x86 cpuid features leaves related to Hyper-V emulation in
KVM. Userspace can use the information returned by this ioctl to construct
cpuid information presented to guests consuming Hyper-V enlightenments (e.g.
Windows or Hyper-V guests).
CPUID feature leaves returned by this ioctl are defined by Hyper-V Top Level
Functional Specification (TLFS). These leaves can't be obtained with
KVM_GET_SUPPORTED_CPUID ioctl because some of them intersect with KVM feature
leaves (0x40000000, 0x40000001).
Currently, the following list of CPUID leaves are returned:
- HYPERV_CPUID_VENDOR_AND_MAX_FUNCTIONS
- HYPERV_CPUID_INTERFACE
- HYPERV_CPUID_VERSION
- HYPERV_CPUID_FEATURES
- HYPERV_CPUID_ENLIGHTMENT_INFO
- HYPERV_CPUID_IMPLEMENT_LIMITS
- HYPERV_CPUID_NESTED_FEATURES
- HYPERV_CPUID_SYNDBG_VENDOR_AND_MAX_FUNCTIONS
- HYPERV_CPUID_SYNDBG_INTERFACE
- HYPERV_CPUID_SYNDBG_PLATFORM_CAPABILITIES
Userspace invokes KVM_GET_SUPPORTED_HV_CPUID by passing a kvm_cpuid2 structure
with the 'nent' field indicating the number of entries in the variable-size
array 'entries'. If the number of entries is too low to describe all Hyper-V
feature leaves, an error (E2BIG) is returned. If the number is more or equal
to the number of Hyper-V feature leaves, the 'nent' field is adjusted to the
number of valid entries in the 'entries' array, which is then filled.
'index' and 'flags' fields in 'struct kvm_cpuid_entry2' are currently reserved,
userspace should not expect to get any particular value there.
Note, vcpu version of KVM_GET_SUPPORTED_HV_CPUID is currently deprecated. Unlike
system ioctl which exposes all supported feature bits unconditionally, vcpu
version has the following quirks:
- HYPERV_CPUID_NESTED_FEATURES leaf and HV_X64_ENLIGHTENED_VMCS_RECOMMENDED
feature bit are only exposed when Enlightened VMCS was previously enabled
on the corresponding vCPU (KVM_CAP_HYPERV_ENLIGHTENED_VMCS).
- HV_STIMER_DIRECT_MODE_AVAILABLE bit is only exposed with in-kernel LAPIC.
(presumes KVM_CREATE_IRQCHIP has already been called).
4.119 KVM_ARM_VCPU_FINALIZE
5129-5170`KVM_ARM_VCPU_FINALIZE`는 arm64 vCPU feature 구성을 확정합니다. 현재 인식하는 feature는 `KVM_CAP_ARM_SVE`가 필요한 `KVM_ARM_VCPU_SVE`입니다.
errno의미
`EPERM`Feature 미활성, 추가 구성 필요 또는 이미 finalize됨
`EINVAL`알 수 없거나 존재하지 않는 feature
Feature enable·configuration·확정 상태를 검사합니다.
해당 feature bit를 넣은 `KVM_ARM_VCPU_INIT`이 먼저 성공해야 합니다. Finalize가 필요한 feature는 이 단계를 거쳐야 vCPU를 완전히 사용할 수 있습니다.
INIT과 FINALIZE 사이에는 `KVM_SET_ONE_REG` 같은 ioctl로 feature별 구성을 조정합니다. 정확한 설정 방법은 feature에 따라 다릅니다.
Finalize 전에는 `KVM_RUN`, `KVM_GET_REG_LIST`, `KVM_GET_ONE_REG`, `KVM_SET_ONE_REG`처럼 해당 feature 확정에 의존하는 호출이 `EPERM`으로 실패합니다.
4.119 KVM_ARM_VCPU_FINALIZE
---------------------------
:Architectures: arm64
:Type: vcpu ioctl
:Parameters: int feature (in)
:Returns: 0 on success, -1 on error
Errors:
====== ==============================================================
EPERM feature not enabled, needs configuration, or already finalized
EINVAL feature unknown or not present
====== ==============================================================
Recognised values for feature:
===== ===========================================
arm64 KVM_ARM_VCPU_SVE (requires KVM_CAP_ARM_SVE)
===== ===========================================
Finalizes the configuration of the specified vcpu feature.
The vcpu must already have been initialised, enabling the affected feature, by
means of a successful :ref:`KVM_ARM_VCPU_INIT <KVM_ARM_VCPU_INIT>` call with the
appropriate flag set in features[].
For affected vcpu features, this is a mandatory step that must be performed
before the vcpu is fully usable.
Between KVM_ARM_VCPU_INIT and KVM_ARM_VCPU_FINALIZE, the feature may be
configured by use of ioctls such as KVM_SET_ONE_REG. The exact configuration
that should be performed and how to do it are feature-dependent.
Other calls that depend on a particular feature being finalized, such as
KVM_RUN, KVM_GET_REG_LIST, KVM_GET_ONE_REG and KVM_SET_ONE_REG, will fail with
-EPERM unless the feature has already been finalized by means of a
KVM_ARM_VCPU_FINALIZE call.
See KVM_ARM_VCPU_INIT for details of vcpu features that require finalization
using this ioctl.
4.120 KVM_SET_PMU_EVENT_FILTER
5171-5286`KVM_SET_PMU_EVENT_FILTER`는 x86 `KVM_CAP_PMU_EVENT_FILTER` VM ioctl로 guest가 program할 수 있는 PMU event-select와 unit-mask 조합을 제한합니다.
errno의미
`EFAULT`입력 argument 접근 불가
`EINVAL`Filter 또는 event data가 잘못됨
`E2BIG``nevents`가 너무 큼
`EBUSY`Filter memory 할당 실패
입력 접근·크기·encoding과 allocation을 검사합니다.
Field의미
`action``KVM_PMU_EVENT_ALLOW` 또는 `_DENY`
`nevents`가변 `events[]` entry 수
`fixed_counter_bitmap`Fixed-purpose counter 선택
`flags`0 또는 `KVM_PMU_EVENT_FLAG_MASKED_EVENTS`
`events[]`Event-select와 unit-mask filter
General counter 목록과 fixed counter bitmap을 함께 제어합니다.
Flags 0 mode에서 각 entry는 event select와 unit mask를 담고 guest가 PMU를 program할 때 정확한 조합을 filter 목록과 비교합니다. `events[]`는 general-purpose counter를 제어하고 fixed counter는 별도 bitmap이 우선합니다.
Masked-event mode는 `KVM_CAP_PMU_EVENT_MASKED_EVENTS`가 필요하며 `KVM_PMU_ENCODE_MASKED_ENTRY()`로 event select, unit-mask match·mask, exclude bit를 encode합니다.
Bits내용
7:0Event select 하위 bit
15:8Unit-mask match
31:16미사용
35:32Event select 상위 bit
54:36미사용
55Exclude bit
63:56Unit-mask mask
원문 encoding을 field 단위로 정리합니다.
판정은 먼저 event select를 찾고, 포함 entry에서 `(unit_mask & mask) == match && !exclude`, 제외 entry에서 같은 비교와 `exclude`를 검사합니다. 포함 match가 있고 제외 match가 없을 때만 event가 filter에 match한 것으로 봅니다.
Match한 event는 allow-list action이면 허용하고 deny-list action이면 거부합니다. Intel에서 미사용 field가 set되거나 event-select 상위 bit 35:32가 set되면 `EINVAL`입니다.
Fixed counter i의 허용 여부는 ALLOW일 때 bitmap bit set, DENY일 때 bit clear입니다. KVM은 항상 `fixed_counter_bitmap`을 소비하므로 general counter만 filter하려는 경우에도 userspace가 올바른 값을 설정해야 합니다.
`events[]`는 fixed counter의 hardcoded event-select·unit-mask에도 적용되지만 둘이 충돌하면 `fixed_counter_bitmap`이 우선합니다.
4.120 KVM_SET_PMU_EVENT_FILTER
------------------------------
:Capability: KVM_CAP_PMU_EVENT_FILTER
:Architectures: x86
:Type: vm ioctl
:Parameters: struct kvm_pmu_event_filter (in)
:Returns: 0 on success, -1 on error
Errors:
====== ============================================================
EFAULT args[0] cannot be accessed
EINVAL args[0] contains invalid data in the filter or filter events
E2BIG nevents is too large
EBUSY not enough memory to allocate the filter
====== ============================================================
::
struct kvm_pmu_event_filter {
__u32 action;
__u32 nevents;
__u32 fixed_counter_bitmap;
__u32 flags;
__u32 pad[4];
__u64 events[0];
};
This ioctl restricts the set of PMU events the guest can program by limiting
which event select and unit mask combinations are permitted.
The argument holds a list of filter events which will be allowed or denied.
Filter events only control general purpose counters; fixed purpose counters
are controlled by the fixed_counter_bitmap.
Valid values for 'flags'::
``0``
To use this mode, clear the 'flags' field.
In this mode each event will contain an event select + unit mask.
When the guest attempts to program the PMU the guest's event select +
unit mask is compared against the filter events to determine whether the
guest should have access.
``KVM_PMU_EVENT_FLAG_MASKED_EVENTS``
:Capability: KVM_CAP_PMU_EVENT_MASKED_EVENTS
In this mode each filter event will contain an event select, mask, match, and
exclude value. To encode a masked event use::
KVM_PMU_ENCODE_MASKED_ENTRY()
An encoded event will follow this layout::
Bits Description
---- -----------
7:0 event select (low bits)
15:8 umask match
31:16 unused
35:32 event select (high bits)
36:54 unused
55 exclude bit
63:56 umask mask
When the guest attempts to program the PMU, these steps are followed in
determining if the guest should have access:
1. Match the event select from the guest against the filter events.
2. If a match is found, match the guest's unit mask to the mask and match
values of the included filter events.
I.e. (unit mask & mask) == match && !exclude.
3. If a match is found, match the guest's unit mask to the mask and match
values of the excluded filter events.
I.e. (unit mask & mask) == match && exclude.
4.
a. If an included match is found and an excluded match is not found, filter
the event.
b. For everything else, do not filter the event.
5.
a. If the event is filtered and it's an allow list, allow the guest to
program the event.
b. If the event is filtered and it's a deny list, do not allow the guest to
program the event.
When setting a new pmu event filter, -EINVAL will be returned if any of the
unused fields are set or if any of the high bits (35:32) in the event
select are set when called on Intel.
Valid values for 'action'::
#define KVM_PMU_EVENT_ALLOW 0
#define KVM_PMU_EVENT_DENY 1
Via this API, KVM userspace can also control the behavior of the VM's fixed
counters (if any) by configuring the "action" and "fixed_counter_bitmap" fields.
Specifically, KVM follows the following pseudo-code when determining whether to
allow the guest FixCtr[i] to count its pre-defined fixed event::
FixCtr[i]_is_allowed = (action == ALLOW) && (bitmap & BIT(i)) ||
(action == DENY) && !(bitmap & BIT(i));
FixCtr[i]_is_denied = !FixCtr[i]_is_allowed;
KVM always consumes fixed_counter_bitmap, it's userspace's responsibility to
ensure fixed_counter_bitmap is set correctly, e.g. if userspace wants to define
a filter that only affects general purpose counters.
Note, the "events" field also applies to fixed counters' hardcoded event_select
and unit_mask values. "fixed_counter_bitmap" has higher priority than "events"
if there is a contradiction between the two.
4.121 KVM_PPC_SVM_OFF
5287-5310`KVM_PPC_SVM_OFF`은 PowerPC secure guest를 normal mode로 전환하며 guest reset 때 호출합니다. Normal guest에 호출하면 효과가 없습니다.
Ultravisor call로 secure guest를 종료하고 VPA page를 unpin하며 hypervisor가 secure page 추적에 사용한 device page를 해제합니다.
Ultravisor가 secure guest 종료에 실패하면 `EINVAL`, hypervisor가 새 radix page table을 할당하지 못하면 `ENOMEM`입니다.
4.121 KVM_PPC_SVM_OFF
---------------------
:Capability: basic
:Architectures: powerpc
:Type: vm ioctl
:Parameters: none
:Returns: 0 on successful completion,
Errors:
====== ================================================================
EINVAL if ultravisor failed to terminate the secure guest
ENOMEM if hypervisor failed to allocate new radix page tables for guest
====== ================================================================
This ioctl is used to turn off the secure mode of the guest or transition
the guest from secure mode to normal mode. This is invoked when the guest
is reset. This has no effect if called for a normal guest.
This ioctl issues an ultravisor call to terminate the secure guest,
unpins the VPA pages and releases all the device pages that are used to
track the secure pages by hypervisor.
4.122 KVM_S390_NORMAL_RESET
5311-5322`KVM_S390_NORMAL_RESET`은 `KVM_CAP_S390_VCPU_RESETS` s390 vCPU ioctl로 POP(Principles of Operation)의 normal CPU reset 정의에 따라 register와 control structure를 reset합니다.
4.122 KVM_S390_NORMAL_RESET
---------------------------
:Capability: KVM_CAP_S390_VCPU_RESETS
:Architectures: s390
:Type: vcpu ioctl
:Parameters: none
:Returns: 0
This ioctl resets VCPU registers and control structures according to
the cpu reset definition in the POP (Principles Of Operation).
4.123 KVM_S390_INITIAL_RESET
5323-5335`KVM_S390_INITIAL_RESET`은 POP의 initial CPU reset에 따라 s390 vCPU register와 control structure를 reset하되 CPU를 ESA mode에 넣지 않습니다. Normal reset의 상위 집합입니다.
4.123 KVM_S390_INITIAL_RESET
----------------------------
:Capability: basic
:Architectures: s390
:Type: vcpu ioctl
:Parameters: none
:Returns: 0
This ioctl resets VCPU registers and control structures according to
the initial cpu reset definition in the POP. However, the cpu is not
put into ESA mode. This reset is a superset of the normal reset.
4.124 KVM_S390_CLEAR_RESET
5336-5349`KVM_S390_CLEAR_RESET`은 POP의 clear CPU reset에 따라 s390 vCPU register와 control structure를 reset하되 CPU를 ESA mode에 넣지 않습니다. Initial reset의 상위 집합입니다.
4.124 KVM_S390_CLEAR_RESET
--------------------------
:Capability: KVM_CAP_S390_VCPU_RESETS
:Architectures: s390
:Type: vcpu ioctl
:Parameters: none
:Returns: 0
This ioctl resets VCPU registers and control structures according to
the clear cpu reset definition in the POP. However, the cpu is not put
into ESA mode. This reset is a superset of the initial reset.
4.125 KVM_S390_PV_COMMAND
5350-5552`KVM_S390_PV_COMMAND`는 `KVM_CAP_S390_PROTECTED` VM ioctl로 s390 protected-virtualization lifecycle, image 준비, dump와 asynchronous teardown을 제어합니다.
Field의미
`cmd`실행할 PV command
`rc`Ultravisor return code
`rrc`Ultravisor return reason code
`data`Command data 또는 address
`flags`향후 확장용, 현재 반드시 0
ioctl 결과와 Ultravisor 결과를 분리해 전달합니다.
Ultravisor call이 실행되면 kernel이 `rc`·`rrc`를 제공하며 ioctl return과 독립적입니다. KVM이 `rc`를 바꾸면 항상 0보다 크므로 호출 전에 0으로 초기화하면 변경을 감지할 수 있습니다.
Command동작
`KVM_PV_ENABLE`VM을 Ultravisor에 등록하고 memory를 기부하며 기존·향후 hotplug CPU를 protected로 전환
`KVM_PV_DISABLE`VM 등록 해제, 기부 memory 회수, 모든 vCPU를 non-protected로 복귀
`KVM_PV_VM_SET_SEC_PARMS`Image unpack·verification 준비를 위해 VM memory의 image header 전달
`KVM_PV_VM_UNPACK`Encrypted boot image page를 protect·decrypt하여 unpack
`KVM_PV_VM_VERIFY`Unpacked image integrity 검증; 성공해야 protected vCPU 시작 가능
Protected VM 생성부터 image 검증까지의 단계입니다.
`KVM_PV_ENABLE` 중 unmasked signal이 pending이면 `EINTR`입니다. `KVM_PV_DISABLE`은 이전 VM의 async cleanup이 PREPARE 뒤 PERFORM되지 않았다면 현재 VM과 함께 그것도 teardown합니다.
`KVM_PV_INFO`는 `KVM_CAP_S390_PROTECTED_DUMP`에서 Ultravisor 정보를 subcommand별로 제공합니다. Header의 `len_max`는 userspace buffer 크기, `len_written`은 실제 기록 byte 수이며 향후 field 추가 시 유효 범위를 판별합니다.
Subcommand결과
`KVM_PV_INFO_VM`설치된 UV call, max PV vCPU·guest·guest address, feature indication
`KVM_PV_INFO_DUMP`CPU dump buffer 길이, 1MiB당 config-memory buffer, finalize-data 길이
Host capability와 dump buffer 요구량을 조회합니다.
VM info는 sysfs firmware UV query에도 있을 수 있지만 이 API가 program에서 사용하기 쉽습니다. `inst_calls_list[4]`, `max_cpus`, `max_guests`, `max_guest_addr`, `feature_indication`을 반환합니다.
`KVM_PV_DUMP`는 protected VM dump를 지원합니다. `struct kvm_s390_pv_dmp`는 `subcmd`, buffer address·length와 storage-state용 absolute guest address `gaddr`를 담습니다.
Subcommand동작
`KVM_PV_DUMP_INIT`Dump process 초기화; 성공 전 다른 subcommand는 `EINVAL`
`KVM_PV_DUMP_CONFIG_STOR_STATE`지정 1MiB block부터 tweak-component 값을 buffer에 저장
`KVM_PV_DUMP_COMPLETE`Dump 완료 후 재초기화를 허용하고 복호화용 completion data 저장
Protected dump의 순차 단계입니다.
모든 PV VM을 dump할 수 있는 것은 아니며 owner가 SE header의 PCF bit 34인 dump-allowed를 set해야 합니다.
CONFIG_STOR_STATE의 `buff_len`은 UV info의 storage-state length 이상이며 그 값에 정렬되어야 합니다. 오류 rc가 돌아와도 fault 전 첫 page처럼 buffer 일부가 기록될 수 있습니다.
DUMP_COMPLETE 성공 시 `conf_dump_finalize_len` byte의 completion data가 기록됩니다. 여기에는 추후 dump 복호화에 필요한 key-derivation seed, IV, tweak nonce, encryption key와 authentication tag가 포함됩니다.
`KVM_PV_ASYNC_CLEANUP_PREPARE`는 현재 protected VM resource 대부분을 별도 보관하고 VM을 즉시 non-protected로 실행 재개시킵니다. 동시에 teardown 준비 상태인 protected VM은 최대 하나입니다.
이미 준비된 VM이 있고 PERFORM하지 않았다면 PREPARE가 실패하므로 userspace는 일반 `KVM_PV_DISABLE`을 호출해야 합니다. 보관 resource는 후속 PERFORM·DISABLE 또는 KVM 종료 때 정리됩니다. Cleanup이 시작되면 이전 PERFORM 완료 전에도 새 PREPARE가 가능합니다.
`KVM_PV_ASYNC_CLEANUP_PERFORM`은 준비된 VM을 teardown하며 별도 userspace thread에서 호출하는 것이 좋습니다. Fatal signal 또는 process 종료로 중단되면 일반 KVM shutdown이 남은 protected VM과 중단된 teardown resource를 정리합니다.
4.125 KVM_S390_PV_COMMAND
-------------------------
:Capability: KVM_CAP_S390_PROTECTED
:Architectures: s390
:Type: vm ioctl
:Parameters: struct kvm_pv_cmd
:Returns: 0 on success, < 0 on error
::
struct kvm_pv_cmd {
__u32 cmd; /* Command to be executed */
__u16 rc; /* Ultravisor return code */
__u16 rrc; /* Ultravisor return reason code */
__u64 data; /* Data or address */
__u32 flags; /* flags for future extensions. Must be 0 for now */
__u32 reserved[3];
};
**Ultravisor return codes**
The Ultravisor return (reason) codes are provided by the kernel if a
Ultravisor call has been executed to achieve the results expected by
the command. Therefore they are independent of the IOCTL return
code. If KVM changes `rc`, its value will always be greater than 0
hence setting it to 0 before issuing a PV command is advised to be
able to detect a change of `rc`.
**cmd values:**
KVM_PV_ENABLE
Allocate memory and register the VM with the Ultravisor, thereby
donating memory to the Ultravisor that will become inaccessible to
KVM. All existing CPUs are converted to protected ones. After this
command has succeeded, any CPU added via hotplug will become
protected during its creation as well.
Errors:
===== =============================
EINTR an unmasked signal is pending
===== =============================
KVM_PV_DISABLE
Deregister the VM from the Ultravisor and reclaim the memory that had
been donated to the Ultravisor, making it usable by the kernel again.
All registered VCPUs are converted back to non-protected ones. If a
previous protected VM had been prepared for asynchronous teardown with
KVM_PV_ASYNC_CLEANUP_PREPARE and not subsequently torn down with
KVM_PV_ASYNC_CLEANUP_PERFORM, it will be torn down in this call
together with the current protected VM.
KVM_PV_VM_SET_SEC_PARMS
Pass the image header from VM memory to the Ultravisor in
preparation of image unpacking and verification.
KVM_PV_VM_UNPACK
Unpack (protect and decrypt) a page of the encrypted boot image.
KVM_PV_VM_VERIFY
Verify the integrity of the unpacked image. Only if this succeeds,
KVM is allowed to start protected VCPUs.
KVM_PV_INFO
:Capability: KVM_CAP_S390_PROTECTED_DUMP
Presents an API that provides Ultravisor related data to userspace
via subcommands. len_max is the size of the user space buffer,
len_written is KVM's indication of how much bytes of that buffer
were actually written to. len_written can be used to determine the
valid fields if more response fields are added in the future.
::
enum pv_cmd_info_id {
KVM_PV_INFO_VM,
KVM_PV_INFO_DUMP,
};
struct kvm_s390_pv_info_header {
__u32 id;
__u32 len_max;
__u32 len_written;
__u32 reserved;
};
struct kvm_s390_pv_info {
struct kvm_s390_pv_info_header header;
struct kvm_s390_pv_info_dump dump;
struct kvm_s390_pv_info_vm vm;
};
**subcommands:**
KVM_PV_INFO_VM
This subcommand provides basic Ultravisor information for PV
hosts. These values are likely also exported as files in the sysfs
firmware UV query interface but they are more easily available to
programs in this API.
The installed calls and feature_indication members provide the
installed UV calls and the UV's other feature indications.
The max_* members provide information about the maximum number of PV
vcpus, PV guests and PV guest memory size.
::
struct kvm_s390_pv_info_vm {
__u64 inst_calls_list[4];
__u64 max_cpus;
__u64 max_guests;
__u64 max_guest_addr;
__u64 feature_indication;
};
KVM_PV_INFO_DUMP
This subcommand provides information related to dumping PV guests.
::
struct kvm_s390_pv_info_dump {
__u64 dump_cpu_buffer_len;
__u64 dump_config_mem_buffer_per_1m;
__u64 dump_config_finalize_len;
};
KVM_PV_DUMP
:Capability: KVM_CAP_S390_PROTECTED_DUMP
Presents an API that provides calls which facilitate dumping a
protected VM.
::
struct kvm_s390_pv_dmp {
__u64 subcmd;
__u64 buff_addr;
__u64 buff_len;
__u64 gaddr; /* For dump storage state */
};
**subcommands:**
KVM_PV_DUMP_INIT
Initializes the dump process of a protected VM. If this call does
not succeed all other subcommands will fail with -EINVAL. This
subcommand will return -EINVAL if a dump process has not yet been
completed.
Not all PV vms can be dumped, the owner needs to set `dump
allowed` PCF bit 34 in the SE header to allow dumping.
KVM_PV_DUMP_CONFIG_STOR_STATE
Stores `buff_len` bytes of tweak component values starting with
the 1MB block specified by the absolute guest address
(`gaddr`). `buff_len` needs to be `conf_dump_storage_state_len`
aligned and at least >= the `conf_dump_storage_state_len` value
provided by the dump uv_info data. buff_user might be written to
even if an error rc is returned. For instance if we encounter a
fault after writing the first page of data.
KVM_PV_DUMP_COMPLETE
If the subcommand succeeds it completes the dump process and lets
KVM_PV_DUMP_INIT be called again.
On success `conf_dump_finalize_len` bytes of completion data will be
stored to the `buff_addr`. The completion data contains a key
derivation seed, IV, tweak nonce and encryption keys as well as an
authentication tag all of which are needed to decrypt the dump at a
later time.
KVM_PV_ASYNC_CLEANUP_PREPARE
:Capability: KVM_CAP_S390_PROTECTED_ASYNC_DISABLE
Prepare the current protected VM for asynchronous teardown. Most
resources used by the current protected VM will be set aside for a
subsequent asynchronous teardown. The current protected VM will then
resume execution immediately as non-protected. There can be at most
one protected VM prepared for asynchronous teardown at any time. If
a protected VM had already been prepared for teardown without
subsequently calling KVM_PV_ASYNC_CLEANUP_PERFORM, this call will
fail. In that case, the userspace process should issue a normal
KVM_PV_DISABLE. The resources set aside with this call will need to
be cleaned up with a subsequent call to KVM_PV_ASYNC_CLEANUP_PERFORM
or KVM_PV_DISABLE, otherwise they will be cleaned up when KVM
terminates. KVM_PV_ASYNC_CLEANUP_PREPARE can be called again as soon
as cleanup starts, i.e. before KVM_PV_ASYNC_CLEANUP_PERFORM finishes.
KVM_PV_ASYNC_CLEANUP_PERFORM
:Capability: KVM_CAP_S390_PROTECTED_ASYNC_DISABLE
Tear down the protected VM previously prepared for teardown with
KVM_PV_ASYNC_CLEANUP_PREPARE. The resources that had been set aside
will be freed during the execution of this command. This PV command
should ideally be issued by userspace from a separate thread. If a
fatal signal is received (or the process terminates naturally), the
command will terminate immediately without completing, and the normal
KVM shutdown procedure will take care of cleaning up all remaining
protected VMs, including the ones whose teardown was interrupted by
process termination.
4.126 KVM_XEN_HVM_SET_ATTR
5553-5675`KVM_XEN_HVM_SET_ATTR`은 x86 Xen HVM VM의 공용 정보 페이지, 이벤트 채널, upcall 벡터와 Xen 버전 같은 VM 전역 속성을 설정하는 VM ioctl입니다. `struct kvm_xen_hvm_attr`의 `type`이 union에서 해석할 필드를 결정합니다.
속성동작
`KVM_XEN_ATTR_TYPE_LONG_MODE`공용 정보 페이지 ABI를 32비트 또는 64비트 long mode로 설정
`KVM_XEN_ATTR_TYPE_SHARED_INFO`Xen `shared_info` 페이지 GFN 설정; `KVM_XEN_INVALID_GFN`으로 비활성화
`KVM_XEN_ATTR_TYPE_SHARED_INFO_HVA`고정 userspace HVA로 `shared_info` 설정; 0으로 비활성화
`KVM_XEN_ATTR_TYPE_UPCALL_VECTOR`HVM 전역 event-channel upcall 예외 벡터 설정; 0으로 비활성화
`KVM_XEN_ATTR_TYPE_EVTCHN`guest `EVTCHNOP_send` 발신 포트를 vCPU/포트 또는 eventfd에 연결
`KVM_XEN_ATTR_TYPE_XEN_VERSION``XENVER_version`에 반환할 32비트 Xen 버전 코드 설정
`KVM_XEN_ATTR_TYPE_RUNSTATE_UPDATE_FLAG`다른 vCPU의 runstate 정보를 안전하게 읽게 하는 update flag 활성화
속성별 입력값과 비활성화 방법입니다.
KVM은 `shared_info`에 첫 32개 vCPU의 `vcpu_info`를 자동 배치하지 않습니다. Xen CPU ID를 모를 수 있으므로 기본 위치에 있더라도 `KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO` 또는 `_HVA`를 명시적으로 설정해야 합니다.
`shared_info`와 `vcpu_info` 페이지는 이벤트 채널 전달 중 KVM이 계속 쓸 수 있지만 매번 dirty로 명시 표시하지는 않습니다. vCPU가 실행됐거나 이벤트 채널이 전달될 수 있었다면 userspace는 해당 페이지를 항상 dirty로 간주해야 합니다.
HVA 속성은 guest 물리 주소 재매핑 때 내부 캐시를 불필요하게 무효화하지 않으므로 지원되는 경우 GFN 속성보다 우선 사용합니다.
`EVTCHN` 속성은 `KVM_XEN_HVM_CONFIG_EVTCHN_SEND`가 필요합니다. vCPU와 priority는 `KVM_XEN_EVTCHN_UPDATE`로 바꿀 수 있고 `KVM_XEN_EVTCHN_DEASSIGN`은 한 매핑을, `KVM_XEN_EVTCHN_RESET`은 모든 발신 interception을 제거합니다. flags 값은 서로 배타적입니다.
Xen 버전 코드는 보통 `(XEN_MAJOR << 16 | XEN_MINOR)`입니다. PV Xen guest가 이벤트 전달을 유도하는 더미 hypercall로 이를 자주 사용하므로 kernel 안에서 응답하면 userspace exit를 줄일 수 있습니다.
4.126 KVM_XEN_HVM_SET_ATTR
--------------------------
:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO
:Architectures: x86
:Type: vm ioctl
:Parameters: struct kvm_xen_hvm_attr
:Returns: 0 on success, < 0 on error
::
struct kvm_xen_hvm_attr {
__u16 type;
__u16 pad[3];
union {
__u8 long_mode;
__u8 vector;
__u8 runstate_update_flag;
union {
__u64 gfn;
__u64 hva;
} shared_info;
struct {
__u32 send_port;
__u32 type; /* EVTCHNSTAT_ipi / EVTCHNSTAT_interdomain */
__u32 flags;
union {
struct {
__u32 port;
__u32 vcpu;
__u32 priority;
} port;
struct {
__u32 port; /* Zero for eventfd */
__s32 fd;
} eventfd;
__u32 padding[4];
} deliver;
} evtchn;
__u32 xen_version;
__u64 pad[8];
} u;
};
type values:
KVM_XEN_ATTR_TYPE_LONG_MODE
Sets the ABI mode of the VM to 32-bit or 64-bit (long mode). This
determines the layout of the shared_info page exposed to the VM.
KVM_XEN_ATTR_TYPE_SHARED_INFO
Sets the guest physical frame number at which the Xen shared_info
page resides. Note that although Xen places vcpu_info for the first
32 vCPUs in the shared_info page, KVM does not automatically do so
and instead requires that KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO or
KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO_HVA be used explicitly even when
the vcpu_info for a given vCPU resides at the "default" location
in the shared_info page. This is because KVM may not be aware of
the Xen CPU id which is used as the index into the vcpu_info[]
array, so may know the correct default location.
Note that the shared_info page may be constantly written to by KVM;
it contains the event channel bitmap used to deliver interrupts to
a Xen guest, amongst other things. It is exempt from dirty tracking
mechanisms — KVM will not explicitly mark the page as dirty each
time an event channel interrupt is delivered to the guest! Thus,
userspace should always assume that the designated GFN is dirty if
any vCPU has been running or any event channel interrupts can be
routed to the guest.
Setting the gfn to KVM_XEN_INVALID_GFN will disable the shared_info
page.
KVM_XEN_ATTR_TYPE_SHARED_INFO_HVA
If the KVM_XEN_HVM_CONFIG_SHARED_INFO_HVA flag is also set in the
Xen capabilities, then this attribute may be used to set the
userspace address at which the shared_info page resides, which
will always be fixed in the VMM regardless of where it is mapped
in guest physical address space. This attribute should be used in
preference to KVM_XEN_ATTR_TYPE_SHARED_INFO as it avoids
unnecessary invalidation of an internal cache when the page is
re-mapped in guest physical address space.
Setting the hva to zero will disable the shared_info page.
KVM_XEN_ATTR_TYPE_UPCALL_VECTOR
Sets the exception vector used to deliver Xen event channel upcalls.
This is the HVM-wide vector injected directly by the hypervisor
(not through the local APIC), typically configured by a guest via
HVM_PARAM_CALLBACK_IRQ. This can be disabled again (e.g. for guest
SHUTDOWN_soft_reset) by setting it to zero.
KVM_XEN_ATTR_TYPE_EVTCHN
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates
support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It configures
an outbound port number for interception of EVTCHNOP_send requests
from the guest. A given sending port number may be directed back to
a specified vCPU (by APIC ID) / port / priority on the guest, or to
trigger events on an eventfd. The vCPU and priority can be changed
by setting KVM_XEN_EVTCHN_UPDATE in a subsequent call, but other
fields cannot change for a given sending port. A port mapping is
removed by using KVM_XEN_EVTCHN_DEASSIGN in the flags field. Passing
KVM_XEN_EVTCHN_RESET in the flags field removes all interception of
outbound event channels. The values of the flags field are mutually
exclusive and cannot be combined as a bitmask.
KVM_XEN_ATTR_TYPE_XEN_VERSION
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates
support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It configures
the 32-bit version code returned to the guest when it invokes the
XENVER_version call; typically (XEN_MAJOR << 16 | XEN_MINOR). PV
Xen guests will often use this to as a dummy hypercall to trigger
event channel delivery, so responding within the kernel without
exiting to userspace is beneficial.
KVM_XEN_ATTR_TYPE_RUNSTATE_UPDATE_FLAG
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates
support for KVM_XEN_HVM_CONFIG_RUNSTATE_UPDATE_FLAG. It enables the
XEN_RUNSTATE_UPDATE flag which allows guest vCPUs to safely read
other vCPUs' vcpu_runstate_info. Xen guests enable this feature via
the VMASST_TYPE_runstate_update_flag of the HYPERVISOR_vm_assist
hypercall.
4.127 KVM_XEN_HVM_GET_ATTR
5676-5688`KVM_XEN_HVM_GET_ATTR`은 `KVM_XEN_HVM_SET_ATTR`과 같은 `struct kvm_xen_hvm_attr` 형식으로 Xen VM 속성을 읽습니다. 단, `KVM_XEN_ATTR_TYPE_EVTCHN` 속성은 읽을 수 없습니다.
4.127 KVM_XEN_HVM_GET_ATTR
--------------------------
:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO
:Architectures: x86
:Type: vm ioctl
:Parameters: struct kvm_xen_hvm_attr
:Returns: 0 on success, < 0 on error
Allows Xen VM attributes to be read. For the structure and types,
see KVM_XEN_HVM_SET_ATTR above. The KVM_XEN_ATTR_TYPE_EVTCHN
attribute cannot be read.
4.128 KVM_XEN_VCPU_SET_ATTR
5689-5802`KVM_XEN_VCPU_SET_ATTR`은 Xen HVM용 x86 vCPU ioctl로 `vcpu_info`, pvclock, runstate, Xen vCPU ID, timer와 로컬 upcall 벡터를 설정합니다.
속성동작
`KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO``vcpu_info` GPA 설정; `KVM_XEN_INVALID_GPA`로 비활성화
`KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO_HVA`기본 `shared_info` 위치의 `vcpu_info`를 고정 HVA로 설정
`KVM_XEN_VCPU_ATTR_TYPE_VCPU_TIME_INFO`vsyscall 등에 쓰는 추가 pvclock GPA 설정
`KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADDR`steal time 등을 기록하는 `vcpu_runstate_info` GPA 설정
`KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_CURRENT`현재 running/runnable/blocked/offline 상태 설정
`KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_DATA`현재 상태와 모든 누적 runstate 시간 복원
`KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADJUST`runstate 시간과 선택적 현재 상태를 원자적으로 가산
`KVM_XEN_VCPU_ATTR_TYPE_VCPU_ID`timer VCPU operation interception용 Xen vCPU ID 설정
`KVM_XEN_VCPU_ATTR_TYPE_TIMER``VIRQ_TIMER`의 포트·priority·만료 시각 설정; 포트 0은 kernel 처리 비활성화
`KVM_XEN_VCPU_ATTR_TYPE_UPCALL_VECTOR`vCPU별 local APIC upcall 벡터 설정; 0으로 비활성화
`struct kvm_xen_vcpu_attr.u`에서 속성에 맞는 필드를 사용합니다.
HVA 형식은 `vcpu_info`가 `shared_info`의 기본 위치에 있을 때만 사용해야 합니다. 다른 위치라면 guest memory layout 변경 뒤 host 주소가 유지된다는 보장이 없어 내부 캐시 무효화가 필요합니다.
KVM은 running과 runnable 시간을 자동 계산하지만 blocked와 offline 상태에는 명시적으로 들어갑니다. `RUNSTATE_DATA`의 `state_entry_time`은 나머지 네 시간의 합과 같아야 합니다.
`RUNSTATE_ADJUST`는 각 시간에 입력값을 더합니다. `state_entry_time` 조정값도 나머지 네 조정값의 합이어야 하며 `state`는 -1 또는 유효한 Xen runstate 값이어야 합니다.
vCPU별 local APIC upcall 벡터는 Windows guest가 주로 사용하며 `HVM_PARAM_CALLBACK_IRQ`로 설정하는 HVM 전역 벡터와 별개입니다.
4.128 KVM_XEN_VCPU_SET_ATTR
---------------------------
:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_xen_vcpu_attr
:Returns: 0 on success, < 0 on error
::
struct kvm_xen_vcpu_attr {
__u16 type;
__u16 pad[3];
union {
__u64 gpa;
__u64 pad[4];
struct {
__u64 state;
__u64 state_entry_time;
__u64 time_running;
__u64 time_runnable;
__u64 time_blocked;
__u64 time_offline;
} runstate;
__u32 vcpu_id;
struct {
__u32 port;
__u32 priority;
__u64 expires_ns;
} timer;
__u8 vector;
} u;
};
type values:
KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO
Sets the guest physical address of the vcpu_info for a given vCPU.
As with the shared_info page for the VM, the corresponding page may be
dirtied at any time if event channel interrupt delivery is enabled, so
userspace should always assume that the page is dirty without relying
on dirty logging. Setting the gpa to KVM_XEN_INVALID_GPA will disable
the vcpu_info.
KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO_HVA
If the KVM_XEN_HVM_CONFIG_SHARED_INFO_HVA flag is also set in the
Xen capabilities, then this attribute may be used to set the
userspace address of the vcpu_info for a given vCPU. It should
only be used when the vcpu_info resides at the "default" location
in the shared_info page. In this case it is safe to assume the
userspace address will not change, because the shared_info page is
an overlay on guest memory and remains at a fixed host address
regardless of where it is mapped in guest physical address space
and hence unnecessary invalidation of an internal cache may be
avoided if the guest memory layout is modified.
If the vcpu_info does not reside at the "default" location then
it is not guaranteed to remain at the same host address and
hence the aforementioned cache invalidation is required.
KVM_XEN_VCPU_ATTR_TYPE_VCPU_TIME_INFO
Sets the guest physical address of an additional pvclock structure
for a given vCPU. This is typically used for guest vsyscall support.
Setting the gpa to KVM_XEN_INVALID_GPA will disable the structure.
KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADDR
Sets the guest physical address of the vcpu_runstate_info for a given
vCPU. This is how a Xen guest tracks CPU state such as steal time.
Setting the gpa to KVM_XEN_INVALID_GPA will disable the runstate area.
KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_CURRENT
Sets the runstate (RUNSTATE_running/_runnable/_blocked/_offline) of
the given vCPU from the .u.runstate.state member of the structure.
KVM automatically accounts running and runnable time but blocked
and offline states are only entered explicitly.
KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_DATA
Sets all fields of the vCPU runstate data from the .u.runstate member
of the structure, including the current runstate. The state_entry_time
must equal the sum of the other four times.
KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADJUST
This *adds* the contents of the .u.runstate members of the structure
to the corresponding members of the given vCPU's runstate data, thus
permitting atomic adjustments to the runstate times. The adjustment
to the state_entry_time must equal the sum of the adjustments to the
other four times. The state field must be set to -1, or to a valid
runstate value (RUNSTATE_running, RUNSTATE_runnable, RUNSTATE_blocked
or RUNSTATE_offline) to set the current accounted state as of the
adjusted state_entry_time.
KVM_XEN_VCPU_ATTR_TYPE_VCPU_ID
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates
support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It sets the Xen
vCPU ID of the given vCPU, to allow timer-related VCPU operations to
be intercepted by KVM.
KVM_XEN_VCPU_ATTR_TYPE_TIMER
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates
support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It sets the
event channel port/priority for the VIRQ_TIMER of the vCPU, as well
as allowing a pending timer to be saved/restored. Setting the timer
port to zero disables kernel handling of the singleshot timer.
KVM_XEN_VCPU_ATTR_TYPE_UPCALL_VECTOR
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates
support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It sets the
per-vCPU local APIC upcall vector, configured by a Xen guest with
the HVMOP_set_evtchn_upcall_vector hypercall. This is typically
used by Windows guests, and is distinct from the HVM-wide upcall
vector configured with HVM_PARAM_CALLBACK_IRQ. It is disabled by
setting the vector to zero.
4.129 KVM_XEN_VCPU_GET_ATTR
5803-5817`KVM_XEN_VCPU_GET_ATTR`은 SET ioctl과 같은 구조와 type으로 Xen vCPU 속성을 읽습니다. 가산 명령인 `KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADJUST`는 GET ioctl에 사용할 수 없습니다.
4.129 KVM_XEN_VCPU_GET_ATTR
---------------------------
:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_xen_vcpu_attr
:Returns: 0 on success, < 0 on error
Allows Xen vCPU attributes to be read. For the structure and types,
see KVM_XEN_VCPU_SET_ATTR above.
The KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADJUST type may not be used
with the KVM_XEN_VCPU_GET_ATTR ioctl.
4.130 KVM_ARM_MTE_COPY_TAGS
5818-5855`KVM_ARM_MTE_COPY_TAGS`는 arm64 `KVM_CAP_ARM_MTE` VM ioctl로 guest tag memory와 userspace buffer 사이에 MTE tag를 복사합니다. `guest_ipa`와 `length`는 `PAGE_SIZE` 정렬이어야 하고 길이는 `2^31 - PAGE_SIZE` 이하여야 합니다.
`flags`는 `KVM_ARM_TAGS_TO_GUEST` 또는 `KVM_ARM_TAGS_FROM_GUEST`로 방향을 지정합니다. MTE granule은 16바이트이므로 buffer 크기는 `length / 16`바이트이고 각 byte에 tag 값 하나를 저장해 ptrace MTE tag 형식과 호환됩니다.
복사 전에 실패하면 음수 errno, 일부 tag를 복사한 뒤 실패하면 성공적으로 복사한 byte 수, 완전히 성공하면 요청한 `length`를 반환합니다.
4.130 KVM_ARM_MTE_COPY_TAGS
---------------------------
:Capability: KVM_CAP_ARM_MTE
:Architectures: arm64
:Type: vm ioctl
:Parameters: struct kvm_arm_copy_mte_tags
:Returns: number of bytes copied, < 0 on error (-EINVAL for incorrect
arguments, -EFAULT if memory cannot be accessed).
::
struct kvm_arm_copy_mte_tags {
__u64 guest_ipa;
__u64 length;
void __user *addr;
__u64 flags;
__u64 reserved[2];
};
Copies Memory Tagging Extension (MTE) tags to/from guest tag memory. The
``guest_ipa`` and ``length`` fields must be ``PAGE_SIZE`` aligned.
``length`` must not be bigger than 2^31 - PAGE_SIZE bytes. The ``addr``
field must point to a buffer which the tags will be copied to or from.
``flags`` specifies the direction of copy, either ``KVM_ARM_TAGS_TO_GUEST`` or
``KVM_ARM_TAGS_FROM_GUEST``.
The size of the buffer to store the tags is ``(length / 16)`` bytes
(granules in MTE are 16 bytes long). Each byte contains a single tag
value. This matches the format of ``PTRACE_PEEKMTETAGS`` and
``PTRACE_POKEMTETAGS``.
If an error occurs before any data is copied then a negative error code is
returned. If some tags have been copied before an error occurs then the number
of bytes successfully copied is returned. If the call completes successfully
then ``length`` is returned.
4.131 KVM_GET_SREGS2
5856-5888`KVM_GET_SREGS2`는 x86 vCPU의 segment, descriptor table, control register, EFER, APIC base와 PDPTR을 `struct kvm_sregs2`로 읽으며 지원되는 경우 `KVM_GET_SREGS`를 대체합니다.
`KVM_SREGS2_FLAGS_PDPTRS_VALID`가 설정되면 구조체의 `pdptrs[4]`가 유효합니다.
4.131 KVM_GET_SREGS2
--------------------
:Capability: KVM_CAP_SREGS2
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_sregs2 (out)
:Returns: 0 on success, -1 on error
Reads special registers from the vcpu.
This ioctl (when supported) replaces the KVM_GET_SREGS.
::
struct kvm_sregs2 {
/* out (KVM_GET_SREGS2) / in (KVM_SET_SREGS2) */
struct kvm_segment cs, ds, es, fs, gs, ss;
struct kvm_segment tr, ldt;
struct kvm_dtable gdt, idt;
__u64 cr0, cr2, cr3, cr4, cr8;
__u64 efer;
__u64 apic_base;
__u64 flags;
__u64 pdptrs[4];
};
flags values for ``kvm_sregs2``:
``KVM_SREGS2_FLAGS_PDPTRS_VALID``
Indicates that the struct contains valid PDPTR values.
4.132 KVM_SET_SREGS2
5889-5901`KVM_SET_SREGS2`는 `KVM_GET_SREGS2`와 같은 구조를 입력으로 받아 x86 vCPU의 special register를 쓰며, 지원되는 경우 `KVM_SET_SREGS`를 대체합니다.
4.132 KVM_SET_SREGS2
--------------------
:Capability: KVM_CAP_SREGS2
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_sregs2 (in)
:Returns: 0 on success, -1 on error
Writes special registers into the vcpu.
See KVM_GET_SREGS2 for the data structures.
This ioctl (when supported) replaces the KVM_SET_SREGS.
4.133 KVM_GET_STATS_FD
5902-6104`KVM_GET_STATS_FD`는 모든 architecture에서 VM 또는 vCPU 통계를 binary 형식으로 읽는 file descriptor를 반환합니다. fd 생성 메모리가 부족하면 `ENOMEM`, 열린 fd 한도를 넘으면 `EMFILE`입니다.
Header→ID string→Descriptors→Stats data
각 block은 64비트 offset에 정렬되고 겹치지 않지만 서로 인접하거나 이 순서일 필요는 없습니다.
Header를 제외한 block의 실제 위치는 `id_offset`, `desc_offset`, `data_offset`에서 얻습니다. Data block을 제외한 block은 immutable이므로 한 번 읽은 뒤 `pread` 또는 `lseek`으로 data만 반복 조회할 수 있습니다. 모든 값은 system endianness입니다.
Field의미
`flags`현재 미사용이며 항상 0
`name_size`종단 NUL을 포함한 이름 문자열의 byte 크기
`num_desc`descriptor 수; 각 descriptor가 여러 값을 가질 수 있어 data 값 수와 다를 수 있음
`id_offset`ID string block의 8바이트 정렬 offset
`desc_offset`descriptor block의 8바이트 정렬 offset
`data_offset`통계 data block의 8바이트 정렬 offset
통계 파일의 block 배치와 descriptor 수를 정의합니다.
Descriptor block은 `struct kvm_stats_desc` 배열이며 각 구조 뒤에 `name_size` byte 문자열이 붙습니다. `flags`는 type과 unit, `exponent`는 scale, `size`는 값 수, `offset`은 data block 기준 위치, `bucket_size`는 선형 histogram 폭입니다.
Type의미
`KVM_STATS_TYPE_CUMULATIVE`감소하지 않는 누적 counter; size 1, 읽기·쓰기 가능
`KVM_STATS_TYPE_INSTANT`증감 가능한 순간값; read-only, size 1
`KVM_STATS_TYPE_PEAK`감소하지 않는 최고값; size 1
`KVM_STATS_TYPE_LINEAR_HIST``size`개 bucket과 `bucket_size` 간격의 선형 histogram
`KVM_STATS_TYPE_LOG_HIST`첫 구간 `[0,1)`, 중간은 2의 거듭제곱, 마지막은 `+INF`까지인 histogram
`flags` bit 0-3이 값의 의미와 크기 규칙을 지정합니다.
선형 histogram의 N번째 bucket은 `[bucket_size*(N-1), bucket_size*N)`이고 마지막은 `[bucket_size*(size-1), +INF)`입니다. 로그 histogram의 중간 N번째 bucket은 `[2^(N-2), 2^(N-1))`, 마지막은 `[2^(size-2), +INF)`입니다.
Unit의미
`KVM_STATS_UNIT_NONE`단순 event counter 등 단위 없음
`KVM_STATS_UNIT_BYTES`byte 계열 메모리 크기
`KVM_STATS_UNIT_SECONDS`시간 또는 latency
`KVM_STATS_UNIT_CYCLES`CPU clock cycle
`KVM_STATS_UNIT_BOOLEAN`항상 0 또는 1; peak는 1에서 0으로 돌아가지 않음
`flags` bit 4-7은 값 또는 histogram 구간의 단위를 지정합니다.
Boolean 값은 두 bucket 선형 histogram이 될 수 있지만 로그 histogram은 될 수 없습니다. Histogram에서는 unit이 bucket 범위에 적용되고 bucket 값은 그 범위에 들어간 sample 수입니다.
`flags` bit 8-11과 `exponent`가 scale을 정합니다. `KVM_STATS_BASE_POW10`에서 seconds와 exponent -9는 nanosecond, `KVM_STATS_BASE_POW2`에서 bytes와 exponent 20은 MiB를 뜻합니다.
Stats Data block은 descriptor 순서와 같은 순서의 unsigned 64비트 값 배열입니다.
4.133 KVM_GET_STATS_FD
----------------------
:Capability: KVM_CAP_STATS_BINARY_FD
:Architectures: all
:Type: vm ioctl, vcpu ioctl
:Parameters: none
:Returns: statistics file descriptor on success, < 0 on error
Errors:
====== ======================================================
ENOMEM if the fd could not be created due to lack of memory
EMFILE if the number of opened files exceeds the limit
====== ======================================================
The returned file descriptor can be used to read VM/vCPU statistics data in
binary format. The data in the file descriptor consists of four blocks
organized as follows:
+-------------+
| Header |
+-------------+
| id string |
+-------------+
| Descriptors |
+-------------+
| Stats Data |
+-------------+
Apart from the header starting at offset 0, please be aware that it is
not guaranteed that the four blocks are adjacent or in the above order;
the offsets of the id, descriptors and data blocks are found in the
header. However, all four blocks are aligned to 64 bit offsets in the
file and they do not overlap.
All blocks except the data block are immutable. Userspace can read them
only one time after retrieving the file descriptor, and then use ``pread`` or
``lseek`` to read the statistics repeatedly.
All data is in system endianness.
The format of the header is as follows::
struct kvm_stats_header {
__u32 flags;
__u32 name_size;
__u32 num_desc;
__u32 id_offset;
__u32 desc_offset;
__u32 data_offset;
};
The ``flags`` field is not used at the moment. It is always read as 0.
The ``name_size`` field is the size (in byte) of the statistics name string
(including trailing '\0') which is contained in the "id string" block and
appended at the end of every descriptor.
The ``num_desc`` field is the number of descriptors that are included in the
descriptor block. (The actual number of values in the data block may be
larger, since each descriptor may comprise more than one value).
The ``id_offset`` field is the offset of the id string from the start of the
file indicated by the file descriptor. It is a multiple of 8.
The ``desc_offset`` field is the offset of the Descriptors block from the start
of the file indicated by the file descriptor. It is a multiple of 8.
The ``data_offset`` field is the offset of the Stats Data block from the start
of the file indicated by the file descriptor. It is a multiple of 8.
The id string block contains a string which identifies the file descriptor on
which KVM_GET_STATS_FD was invoked. The size of the block, including the
trailing ``'\0'``, is indicated by the ``name_size`` field in the header.
The descriptors block is only needed to be read once for the lifetime of the
file descriptor contains a sequence of ``struct kvm_stats_desc``, each followed
by a string of size ``name_size``.
::
#define KVM_STATS_TYPE_SHIFT 0
#define KVM_STATS_TYPE_MASK (0xF << KVM_STATS_TYPE_SHIFT)
#define KVM_STATS_TYPE_CUMULATIVE (0x0 << KVM_STATS_TYPE_SHIFT)
#define KVM_STATS_TYPE_INSTANT (0x1 << KVM_STATS_TYPE_SHIFT)
#define KVM_STATS_TYPE_PEAK (0x2 << KVM_STATS_TYPE_SHIFT)
#define KVM_STATS_TYPE_LINEAR_HIST (0x3 << KVM_STATS_TYPE_SHIFT)
#define KVM_STATS_TYPE_LOG_HIST (0x4 << KVM_STATS_TYPE_SHIFT)
#define KVM_STATS_TYPE_MAX KVM_STATS_TYPE_LOG_HIST
#define KVM_STATS_UNIT_SHIFT 4
#define KVM_STATS_UNIT_MASK (0xF << KVM_STATS_UNIT_SHIFT)
#define KVM_STATS_UNIT_NONE (0x0 << KVM_STATS_UNIT_SHIFT)
#define KVM_STATS_UNIT_BYTES (0x1 << KVM_STATS_UNIT_SHIFT)
#define KVM_STATS_UNIT_SECONDS (0x2 << KVM_STATS_UNIT_SHIFT)
#define KVM_STATS_UNIT_CYCLES (0x3 << KVM_STATS_UNIT_SHIFT)
#define KVM_STATS_UNIT_BOOLEAN (0x4 << KVM_STATS_UNIT_SHIFT)
#define KVM_STATS_UNIT_MAX KVM_STATS_UNIT_BOOLEAN
#define KVM_STATS_BASE_SHIFT 8
#define KVM_STATS_BASE_MASK (0xF << KVM_STATS_BASE_SHIFT)
#define KVM_STATS_BASE_POW10 (0x0 << KVM_STATS_BASE_SHIFT)
#define KVM_STATS_BASE_POW2 (0x1 << KVM_STATS_BASE_SHIFT)
#define KVM_STATS_BASE_MAX KVM_STATS_BASE_POW2
struct kvm_stats_desc {
__u32 flags;
__s16 exponent;
__u16 size;
__u32 offset;
__u32 bucket_size;
char name[];
};
The ``flags`` field contains the type and unit of the statistics data described
by this descriptor. Its endianness is CPU native.
The following flags are supported:
Bits 0-3 of ``flags`` encode the type:
* ``KVM_STATS_TYPE_CUMULATIVE``
The statistics reports a cumulative count. The value of data can only be increased.
Most of the counters used in KVM are of this type.
The corresponding ``size`` field for this type is always 1.
All cumulative statistics data are read/write.
* ``KVM_STATS_TYPE_INSTANT``
The statistics reports an instantaneous value. Its value can be increased or
decreased. This type is usually used as a measurement of some resources,
like the number of dirty pages, the number of large pages, etc.
All instant statistics are read only.
The corresponding ``size`` field for this type is always 1.
* ``KVM_STATS_TYPE_PEAK``
The statistics data reports a peak value, for example the maximum number
of items in a hash table bucket, the longest time waited and so on.
The value of data can only be increased.
The corresponding ``size`` field for this type is always 1.
* ``KVM_STATS_TYPE_LINEAR_HIST``
The statistic is reported as a linear histogram. The number of
buckets is specified by the ``size`` field. The size of buckets is specified
by the ``hist_param`` field. The range of the Nth bucket (1 <= N < ``size``)
is [``hist_param``*(N-1), ``hist_param``*N), while the range of the last
bucket is [``hist_param``*(``size``-1), +INF). (+INF means positive infinity
value.)
* ``KVM_STATS_TYPE_LOG_HIST``
The statistic is reported as a logarithmic histogram. The number of
buckets is specified by the ``size`` field. The range of the first bucket is
[0, 1), while the range of the last bucket is [pow(2, ``size``-2), +INF).
Otherwise, The Nth bucket (1 < N < ``size``) covers
[pow(2, N-2), pow(2, N-1)).
Bits 4-7 of ``flags`` encode the unit:
* ``KVM_STATS_UNIT_NONE``
There is no unit for the value of statistics data. This usually means that
the value is a simple counter of an event.
* ``KVM_STATS_UNIT_BYTES``
It indicates that the statistics data is used to measure memory size, in the
unit of Byte, KiByte, MiByte, GiByte, etc. The unit of the data is
determined by the ``exponent`` field in the descriptor.
* ``KVM_STATS_UNIT_SECONDS``
It indicates that the statistics data is used to measure time or latency.
* ``KVM_STATS_UNIT_CYCLES``
It indicates that the statistics data is used to measure CPU clock cycles.
* ``KVM_STATS_UNIT_BOOLEAN``
It indicates that the statistic will always be either 0 or 1. Boolean
statistics of "peak" type will never go back from 1 to 0. Boolean
statistics can be linear histograms (with two buckets) but not logarithmic
histograms.
Note that, in the case of histograms, the unit applies to the bucket
ranges, while the bucket value indicates how many samples fell in the
bucket's range.
Bits 8-11 of ``flags``, together with ``exponent``, encode the scale of the
unit:
* ``KVM_STATS_BASE_POW10``
The scale is based on power of 10. It is used for measurement of time and
CPU clock cycles. For example, an exponent of -9 can be used with
``KVM_STATS_UNIT_SECONDS`` to express that the unit is nanoseconds.
* ``KVM_STATS_BASE_POW2``
The scale is based on power of 2. It is used for measurement of memory size.
For example, an exponent of 20 can be used with ``KVM_STATS_UNIT_BYTES`` to
express that the unit is MiB.
The ``size`` field is the number of values of this statistics data. Its
value is usually 1 for most of simple statistics. 1 means it contains an
unsigned 64bit data.
The ``offset`` field is the offset from the start of Data Block to the start of
the corresponding statistics data.
The ``bucket_size`` field is used as a parameter for histogram statistics data.
It is only used by linear histogram statistics data, specifying the size of a
bucket in the unit expressed by bits 4-11 of ``flags`` together with ``exponent``.
The ``name`` field is the name string of the statistics data. The name string
starts at the end of ``struct kvm_stats_desc``. The maximum length including
the trailing ``'\0'``, is indicated by ``name_size`` in the header.
The Stats Data block contains an array of 64-bit values in the same order
as the descriptors in Descriptors block.
4.134 KVM_GET_XSAVE2
6105-6131`KVM_GET_XSAVE2`는 x86 vCPU의 XSAVE 상태를 userspace로 복사합니다. VM fd에서 `KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2)`가 반환한 byte 수만큼 복사하며 크기는 항상 최소 4096입니다.
현재는 `arch_prctl()`로 dynamic feature를 활성화했을 때만 4096보다 클 수 있지만 이후 달라질 수 있습니다. 각 state-save area의 offset은 host CPUID leaf `0xD`를 따릅니다.
4.134 KVM_GET_XSAVE2
--------------------
:Capability: KVM_CAP_XSAVE2
:Architectures: x86
:Type: vcpu ioctl
:Parameters: struct kvm_xsave (out)
:Returns: 0 on success, -1 on error
::
struct kvm_xsave {
__u32 region[1024];
__u32 extra[0];
};
This ioctl would copy current vcpu's xsave struct to the userspace. It
copies as many bytes as are returned by KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2)
when invoked on the vm file descriptor. The size value returned by
KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2) will always be at least 4096.
Currently, it is only greater than 4096 if a dynamic feature has been
enabled with ``arch_prctl()``, but this may change in the future.
The offsets of the state save areas in struct kvm_xsave follow the contents
of CPUID leaf 0xD on the host.
4.135 KVM_XEN_HVM_EVTCHN_SEND
6132-6151`KVM_XEN_HVM_EVTCHN_SEND`는 `struct kvm_irq_routing_xen_evtchn`의 port, vCPU와 priority를 사용해 Xen event-channel interrupt를 guest vCPU에 직접 주입하는 x86 VM ioctl입니다.
4.135 KVM_XEN_HVM_EVTCHN_SEND
-----------------------------
:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_EVTCHN_SEND
:Architectures: x86
:Type: vm ioctl
:Parameters: struct kvm_irq_routing_xen_evtchn
:Returns: 0 on success, < 0 on error
::
struct kvm_irq_routing_xen_evtchn {
__u32 port;
__u32 vcpu;
__u32 priority;
};
This ioctl injects an event channel interrupt directly to the guest vCPU.
4.136 KVM_S390_PV_CPU_COMMAND
6152-6176`KVM_S390_PV_CPU_COMMAND`는 vCPU 요청을 처리하는 s390 protected-dump ioctl입니다. `KVM_S390_PV_COMMAND`와 같은 `kvm_s390_pv_dmp` 구조와 command ID를 재사용합니다.
`KVM_PV_DUMP_CPU` subcommand는 protected VM vCPU의 register 값 같은 암호화 dump 데이터를 반환하며 길이는 `uv_info.guest_cpu_stor_len`입니다.
4.136 KVM_S390_PV_CPU_COMMAND
-----------------------------
:Capability: KVM_CAP_S390_PROTECTED_DUMP
:Architectures: s390
:Type: vcpu ioctl
:Parameters: none
:Returns: 0 on success, < 0 on error
This ioctl closely mirrors `KVM_S390_PV_COMMAND` but handles requests
for vcpus. It re-uses the kvm_s390_pv_dmp struct and hence also shares
the command ids.
**command:**
KVM_PV_DUMP
Presents an API that provides calls which facilitate dumping a vcpu
of a protected VM.
**subcommand:**
KVM_PV_DUMP_CPU
Provides encrypted dump data like register values.
The length of the returned data is provided by uv_info.guest_cpu_stor_len.
4.137 KVM_S390_ZPCI_OP
6177-6223`KVM_S390_ZPCI_OP`는 s390 zPCI device의 hardware-assisted virtualization 기능을 관리합니다. `fh`로 대상 함수를, `op`로 작업을 지정합니다.
`KVM_S390_ZPCIOP_REG_AEN`은 adapter event notification interpretation을 등록해 firmware가 event를 VM에 직접 전달하게 하고 KVM이 fallback 전달을 제공합니다. `KVM_S390_ZPCIOP_DEREG_AEN`은 이를 해제합니다.
등록 시 `reg_aen`에 interrupt bit vector guest 주소 `ibv`, summary bit 주소 `sb`, interrupt 수 `noi`, guest interrupt subclass `isc`, summary bit vector offset `sbo`와 flags를 제공합니다. `pad`와 `reserved`는 미래 확장용이므로 0이어야 합니다.
4.137 KVM_S390_ZPCI_OP
----------------------
:Capability: KVM_CAP_S390_ZPCI_OP
:Architectures: s390
:Type: vm ioctl
:Parameters: struct kvm_s390_zpci_op (in)
:Returns: 0 on success, <0 on error
Used to manage hardware-assisted virtualization features for zPCI devices.
Parameters are specified via the following structure::
struct kvm_s390_zpci_op {
/* in */
__u32 fh; /* target device */
__u8 op; /* operation to perform */
__u8 pad[3];
union {
/* for KVM_S390_ZPCIOP_REG_AEN */
struct {
__u64 ibv; /* Guest addr of interrupt bit vector */
__u64 sb; /* Guest addr of summary bit */
__u32 flags;
__u32 noi; /* Number of interrupts */
__u8 isc; /* Guest interrupt subclass */
__u8 sbo; /* Offset of guest summary bit vector */
__u16 pad;
} reg_aen;
__u64 reserved[8];
} u;
};
The type of operation is specified in the "op" field.
KVM_S390_ZPCIOP_REG_AEN is used to register the VM for adapter event
notification interpretation, which will allow firmware delivery of adapter
events directly to the vm, with KVM providing a backup delivery mechanism;
KVM_S390_ZPCIOP_DEREG_AEN is used to subsequently disable interpretation of
adapter event notifications.
The target zPCI function must also be specified via the "fh" field. For the
KVM_S390_ZPCIOP_REG_AEN operation, additional information to establish firmware
delivery must be provided via the "reg_aen" struct.
The "pad" and "reserved" fields may be used for future extensions and should be
set to 0s by userspace.
4.138 KVM_ARM_SET_COUNTER_OFFSET
6224-6263`KVM_ARM_SET_COUNTER_OFFSET`은 arm64 VM의 virtual·physical counter view 모두에 VM 전역 offset을 적용합니다. `counter_offset` cycle 수를 두 counter에서 빼며 기존 vCPU와 이후 생성할 vCPU 모두에 적용됩니다.
Userspace는 이전 guest counter 값 등을 기준으로 offset을 계산해야 합니다. `reserved`가 0이 아니면 `EINVAL`, vCPU ioctl과 동시에 실행하면 `EBUSY`가 될 수 있습니다.
이 ioctl을 사용한 뒤 `SET_ONE_REG`로 `CNTVCT_EL0` 또는 `CNTPCT_EL0`에 쓰면 KVM은 오류를 반환하지 않지만 그 쓰기를 무시하고 결과 offset도 적용하지 않습니다.
4.138 KVM_ARM_SET_COUNTER_OFFSET
--------------------------------
:Capability: KVM_CAP_COUNTER_OFFSET
:Architectures: arm64
:Type: vm ioctl
:Parameters: struct kvm_arm_counter_offset (in)
:Returns: 0 on success, < 0 on error
This capability indicates that userspace is able to apply a single VM-wide
offset to both the virtual and physical counters as viewed by the guest
using the KVM_ARM_SET_CNT_OFFSET ioctl and the following data structure:
::
struct kvm_arm_counter_offset {
__u64 counter_offset;
__u64 reserved;
};
The offset describes a number of counter cycles that are subtracted from
both virtual and physical counter views (similar to the effects of the
CNTVOFF_EL2 and CNTPOFF_EL2 system registers, but only global). The offset
always applies to all vcpus (already created or created after this ioctl)
for this VM.
It is userspace's responsibility to compute the offset based, for example,
on previous values of the guest counters.
Any value other than 0 for the "reserved" field may result in an error
(-EINVAL) being returned. This ioctl can also return -EBUSY if any vcpu
ioctl is issued concurrently.
Note that using this ioctl results in KVM ignoring subsequent userspace
writes to the CNTVCT_EL0 and CNTPCT_EL0 registers using the SET_ONE_REG
interface. No error will be returned, but the resulting offset will not be
applied.
.. _KVM_ARM_GET_REG_WRITABLE_MASKS:
4.139 KVM_ARM_GET_REG_WRITABLE_MASKS
6264-6311`KVM_ARM_GET_REG_WRITABLE_MASKS`는 arm64 register 범위의 writable mask를 userspace 배열에 복사합니다. `addr`은 목적지 배열, `range`는 요청 범위이며 `reserved[13]`은 0이어야 합니다.
`KVM_CAP_ARM_SUPPORTED_REG_MASK_RANGES`의 반환값은 지원 범위를 flag 집합으로 표현하고 각 bit index가 가능한 `range` 값입니다. 예약된 값을 요청하면 KVM이 오류를 반환할 수 있습니다.
`KVM_ARM_FEATURE_ID_RANGE`는 system-register 공간 `op0==3`, `op1=={0,1,3}`, `CRn==0`, `CRm=={0-7}`, `op2=={0-7}`입니다. `ARM64_FEATURE_ID_RANGE_IDX()`로 mask 배열을 찾으며 KVM은 system 지원 범위를 초과하는 ID register 값을 거부합니다.
4.139 KVM_ARM_GET_REG_WRITABLE_MASKS
------------------------------------
:Capability: KVM_CAP_ARM_SUPPORTED_REG_MASK_RANGES
:Architectures: arm64
:Type: vm ioctl
:Parameters: struct reg_mask_range (in/out)
:Returns: 0 on success, < 0 on error
::
#define KVM_ARM_FEATURE_ID_RANGE 0
#define KVM_ARM_FEATURE_ID_RANGE_SIZE (3 * 8 * 8)
struct reg_mask_range {
__u64 addr; /* Pointer to mask array */
__u32 range; /* Requested range */
__u32 reserved[13];
};
This ioctl copies the writable masks for a selected range of registers to
userspace.
The ``addr`` field is a pointer to the destination array where KVM copies
the writable masks.
The ``range`` field indicates the requested range of registers.
``KVM_CHECK_EXTENSION`` for the ``KVM_CAP_ARM_SUPPORTED_REG_MASK_RANGES``
capability returns the supported ranges, expressed as a set of flags. Each
flag's bit index represents a possible value for the ``range`` field.
All other values are reserved for future use and KVM may return an error.
The ``reserved[13]`` array is reserved for future use and should be 0, or
KVM may return an error.
KVM_ARM_FEATURE_ID_RANGE (0)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Feature ID range is defined as the AArch64 System register space with
op0==3, op1=={0, 1, 3}, CRn==0, CRm=={0-7}, op2=={0-7}.
The mask returned array pointed to by ``addr`` is indexed by the macro
``ARM64_FEATURE_ID_RANGE_IDX(op0, op1, crn, crm, op2)``, allowing userspace
to know what fields can be changed for the system register described by
``op0, op1, crn, crm, op2``. KVM rejects ID register values that describe a
superset of the features supported by the system.
4.140 KVM_SET_USER_MEMORY_REGION2
6312-6362`KVM_SET_USER_MEMORY_REGION2`는 기존 memory-region API를 확장해 `guest_memfd` memory를 guest에 매핑합니다. 공통 필드는 `KVM_SET_USER_MEMORY_REGION`과 동일하게 동작합니다.
`KVM_MEM_GUEST_MEMFD`를 설정하면 `[guest_memfd_offset, guest_memfd_offset + memory_size]` 범위를 binding합니다. fd는 현재 VM의 `KVM_CREATE_GUEST_MEMFD`로 만든 파일이어야 하고 같은 범위가 다른 region에 이미 binding되어서는 안 됩니다.
Guest-memfd region에는 private memory용 유효한 `guest_memfd`와 shared memory용 유효한 `userspace_addr`가 모두 필요합니다. 다만 호출 시점에 userspace backing mapping이 존재하거나 populate되어 있을 필요는 없어 지연 할당할 수 있습니다.
KVM은 GFN의 `KVM_MEMORY_ATTRIBUTE_PRIVATE` 상태에 따라 shared 접근에는 `userspace_addr`, private 접근에는 `guest_memfd`를 선택합니다. VM 생성 시 모든 GFN은 shared이며 userspace가 `KVM_SET_MEMORY_ATTRIBUTES`로 바꿉니다.
s390에서 `KVM_VM_S390_UCONTROL` VM 또는 protected VM에 호출하면 `EINVAL`입니다.
4.140 KVM_SET_USER_MEMORY_REGION2
---------------------------------
:Capability: KVM_CAP_USER_MEMORY2
:Architectures: all
:Type: vm ioctl
:Parameters: struct kvm_userspace_memory_region2 (in)
:Returns: 0 on success, -1 on error
KVM_SET_USER_MEMORY_REGION2 is an extension to KVM_SET_USER_MEMORY_REGION that
allows mapping guest_memfd memory into a guest. All fields shared with
KVM_SET_USER_MEMORY_REGION identically. Userspace can set KVM_MEM_GUEST_MEMFD
in flags to have KVM bind the memory region to a given guest_memfd range of
[guest_memfd_offset, guest_memfd_offset + memory_size]. The target guest_memfd
must point at a file created via KVM_CREATE_GUEST_MEMFD on the current VM, and
the target range must not be bound to any other memory region. All standard
bounds checks apply (use common sense).
::
struct kvm_userspace_memory_region2 {
__u32 slot;
__u32 flags;
__u64 guest_phys_addr;
__u64 memory_size; /* bytes */
__u64 userspace_addr; /* start of the userspace allocated memory */
__u64 guest_memfd_offset;
__u32 guest_memfd;
__u32 pad1;
__u64 pad2[14];
};
A KVM_MEM_GUEST_MEMFD region _must_ have a valid guest_memfd (private memory) and
userspace_addr (shared memory). However, "valid" for userspace_addr simply
means that the address itself must be a legal userspace address. The backing
mapping for userspace_addr is not required to be valid/populated at the time of
KVM_SET_USER_MEMORY_REGION2, e.g. shared memory can be lazily mapped/allocated
on-demand.
When mapping a gfn into the guest, KVM selects shared vs. private, i.e consumes
userspace_addr vs. guest_memfd, based on the gfn's KVM_MEMORY_ATTRIBUTE_PRIVATE
state. At VM creation time, all memory is shared, i.e. the PRIVATE attribute
is '0' for all gfns. Userspace can control whether memory is shared/private by
toggling KVM_MEMORY_ATTRIBUTE_PRIVATE via KVM_SET_MEMORY_ATTRIBUTES as needed.
S390:
^^^^^
Returns -EINVAL if the VM has the KVM_VM_S390_UCONTROL flag set.
Returns -EINVAL if called on a protected VM.
4.141 KVM_SET_MEMORY_ATTRIBUTES
6363-6398`KVM_SET_MEMORY_ATTRIBUTES`는 guest physical memory 범위의 속성을 설정합니다. `address`와 `size`는 page 정렬이어야 하며 현재 정의된 속성은 GFN을 guest-private memory로 표시하는 `KVM_MEMORY_ATTRIBUTE_PRIVATE`뿐입니다.
VM fd에서 `KVM_CAP_MEMORY_ATTRIBUTES`를 조회하면 그 VM이 지원하는 정확한 속성을, system 범위에서 조회하면 KVM 전체가 지원하는 속성을 반환합니다.
별도의 get API는 없으므로 userspace가 GFN·page 속성을 명시적으로 추적해야 합니다. `flags`는 미래 확장용이며 0이어야 합니다.
4.141 KVM_SET_MEMORY_ATTRIBUTES
-------------------------------
:Capability: KVM_CAP_MEMORY_ATTRIBUTES
:Architectures: x86
:Type: vm ioctl
:Parameters: struct kvm_memory_attributes (in)
:Returns: 0 on success, <0 on error
KVM_SET_MEMORY_ATTRIBUTES allows userspace to set memory attributes for a range
of guest physical memory.
::
struct kvm_memory_attributes {
__u64 address;
__u64 size;
__u64 attributes;
__u64 flags;
};
#define KVM_MEMORY_ATTRIBUTE_PRIVATE (1ULL << 3)
The address and size must be page aligned. The supported attributes can be
retrieved via ioctl(KVM_CHECK_EXTENSION) on KVM_CAP_MEMORY_ATTRIBUTES. If
executed on a VM, KVM_CAP_MEMORY_ATTRIBUTES precisely returns the attributes
supported by that VM. If executed at system scope, KVM_CAP_MEMORY_ATTRIBUTES
returns all attributes supported by KVM. The only attribute defined at this
time is KVM_MEMORY_ATTRIBUTE_PRIVATE, which marks the associated gfn as being
guest private memory.
Note, there is no "get" API. Userspace is responsible for explicitly tracking
the state of a gfn/page as needed.
The "flags" field is reserved for future extensions and must be '0'.
4.142 KVM_CREATE_GUEST_MEMFD
6399-6459`KVM_CREATE_GUEST_MEMFD`는 RAM에 존재하고 마지막 reference가 사라지면 해제되는 익명 guest-memory 파일을 만든 뒤 fd를 반환합니다. 일반 memfd와 달리 소유 VM에 binding되고 userspace가 직접 read·write할 수 없으며 resize할 수 없지만 `PUNCH_HOLE`은 지원합니다.
Backing inode는 특정 `struct kvm`이 아니라 VM의 physical memory 자체를 나타내고, 각 파일은 해당 `struct kvm`의 guest-address-to-host-memory view입니다. 따라서 host 내부 migration처럼 여러 KVM 구조가 한 VM을 관리할 수 있습니다.
현재는 `KVM_SET_USER_MEMORY_REGION2`의 `guest_memfd`와 `guest_memfd_offset`을 통해서만 매핑합니다. 한 파일에 여러 region을 binding할 수 있지만 page별 binding은 하나뿐이므로 범위가 겹치면 안 됩니다.
Flag동작
`GUEST_MEMFD_FLAG_MMAP`guest_memfd fd에 `mmap()` 사용 허용
`GUEST_MEMFD_FLAG_INIT_SHARED`생성 중 파일 전체를 shared로 초기화; 없으면 private로 표시
`KVM_CAP_GUEST_MEMFD_FLAGS`로 지원 flag를 조회합니다.
Shared memory는 host userspace page table에 fault-in할 수 있지만 private memory는 할 수 없습니다. `MMAP` flag가 있으면 KVM MMU는 shared/private fault 여부와 관계없이 guest_memfd에서 처리합니다.
4.142 KVM_CREATE_GUEST_MEMFD
----------------------------
:Capability: KVM_CAP_GUEST_MEMFD
:Architectures: none
:Type: vm ioctl
:Parameters: struct kvm_create_guest_memfd(in)
:Returns: A file descriptor on success, <0 on error
KVM_CREATE_GUEST_MEMFD creates an anonymous file and returns a file descriptor
that refers to it. guest_memfd files are roughly analogous to files created
via memfd_create(), e.g. guest_memfd files live in RAM, have volatile storage,
and are automatically released when the last reference is dropped. Unlike
"regular" memfd_create() files, guest_memfd files are bound to their owning
virtual machine (see below), cannot be mapped, read, or written by userspace,
and cannot be resized (guest_memfd files do however support PUNCH_HOLE).
::
struct kvm_create_guest_memfd {
__u64 size;
__u64 flags;
__u64 reserved[6];
};
Conceptually, the inode backing a guest_memfd file represents physical memory,
i.e. is coupled to the virtual machine as a thing, not to a "struct kvm". The
file itself, which is bound to a "struct kvm", is that instance's view of the
underlying memory, e.g. effectively provides the translation of guest addresses
to host memory. This allows for use cases where multiple KVM structures are
used to manage a single virtual machine, e.g. when performing intrahost
migration of a virtual machine.
KVM currently only supports mapping guest_memfd via KVM_SET_USER_MEMORY_REGION2,
and more specifically via the guest_memfd and guest_memfd_offset fields in
"struct kvm_userspace_memory_region2", where guest_memfd_offset is the offset
into the guest_memfd instance. For a given guest_memfd file, there can be at
most one mapping per page, i.e. binding multiple memory regions to a single
guest_memfd range is not allowed (any number of memory regions can be bound to
a single guest_memfd file, but the bound ranges must not overlap).
The capability KVM_CAP_GUEST_MEMFD_FLAGS enumerates the `flags` that can be
specified via KVM_CREATE_GUEST_MEMFD. Currently defined flags:
============================ ================================================
GUEST_MEMFD_FLAG_MMAP Enable using mmap() on the guest_memfd file
descriptor.
GUEST_MEMFD_FLAG_INIT_SHARED Make all memory in the file shared during
KVM_CREATE_GUEST_MEMFD (memory files created
without INIT_SHARED will be marked private).
Shared memory can be faulted into host userspace
page tables. Private memory cannot.
============================ ================================================
When the KVM MMU performs a PFN lookup to service a guest fault and the backing
guest_memfd has the GUEST_MEMFD_FLAG_MMAP set, then the fault will always be
consumed from guest_memfd, regardless of whether it is a shared or a private
fault.
See KVM_SET_USER_MEMORY_REGION2 for additional details.
4.143 KVM_PRE_FAULT_MEMORY
6460-6522`KVM_PRE_FAULT_MEMORY`는 현재 vCPU 상태에 맞춰 memory를 stage-2 page table에 미리 채웁니다. vCPU가 stage-2 read page fault를 낸 것처럼 필요하면 memory를 fault-in하지만 CoW를 깨지 않고 새 stage-2 PTE를 Accessed로 표시하지 않습니다.
errno조건
`EINVAL`GPA·size가 page 정렬이 아니거나 overflow, 또는 size가 0
`ENOENT`GPA가 정의된 memslot 밖
`EINTR`처리한 page 없이 unmasked signal pending
`EFAULT`argument 주소가 유효하지 않음
`EOPNOTSUPP`현재 hypervisor 또는 vCPU state/mode에서 GPA mapping 미지원
`EIO`예상하지 못한 오류이며 WARN도 발생
GPA 범위와 현재 MMU mode를 검증합니다.
Confidential VM에서 private memory를 초기 구성한 뒤 측정·finalize하는 경우에는 필요한 초기 설정과 finalize를 마친 뒤 호출해야 합니다.
여러 vCPU가 page table을 공유할 때는 병렬 호출할 수 있습니다. 반환 시 `gpa`와 `size`는 처리하지 않은 나머지 범위를 가리키므로 `size > 0`이면 같은 구조로 다시 호출할 수 있습니다.
Shadow page table은 virtual address 또는 nested guest physical address로 index되므로 지원하지 않습니다. Nested guest 실행 등으로 shadow page table을 쓰면 capability가 보고돼도 `EOPNOTSUPP`입니다. 현재 `flags`는 0이어야 합니다.
4.143 KVM_PRE_FAULT_MEMORY
---------------------------
:Capability: KVM_CAP_PRE_FAULT_MEMORY
:Architectures: none
:Type: vcpu ioctl
:Parameters: struct kvm_pre_fault_memory (in/out)
:Returns: 0 if at least one page is processed, < 0 on error
Errors:
========== ===============================================================
EINVAL The specified `gpa` and `size` were invalid (e.g. not
page aligned, causes an overflow, or size is zero).
ENOENT The specified `gpa` is outside defined memslots.
EINTR An unmasked signal is pending and no page was processed.
EFAULT The parameter address was invalid.
EOPNOTSUPP Mapping memory for a GPA is unsupported by the
hypervisor, and/or for the current vCPU state/mode.
EIO unexpected error conditions (also causes a WARN)
========== ===============================================================
::
struct kvm_pre_fault_memory {
/* in/out */
__u64 gpa;
__u64 size;
/* in */
__u64 flags;
__u64 padding[5];
};
KVM_PRE_FAULT_MEMORY populates KVM's stage-2 page tables used to map memory
for the current vCPU state. KVM maps memory as if the vCPU generated a
stage-2 read page fault, e.g. faults in memory as needed, but doesn't break
CoW. However, KVM does not mark any newly created stage-2 PTE as Accessed.
In the case of confidential VM types where there is an initial set up of
private guest memory before the guest is 'finalized'/measured, this ioctl
should only be issued after completing all the necessary setup to put the
guest into a 'finalized' state so that the above semantics can be reliably
ensured.
In some cases, multiple vCPUs might share the page tables. In this
case, the ioctl can be called in parallel.
When the ioctl returns, the input values are updated to point to the
remaining range. If `size` > 0 on return, the caller can just issue
the ioctl again with the same `struct kvm_map_memory` argument.
Shadow page tables cannot support this ioctl because they
are indexed by virtual address or nested guest physical address.
Calling this ioctl when the guest is using shadow page tables (for
example because it is running a nested guest with nested page tables)
will fail with `EOPNOTSUPP` even if `KVM_CHECK_EXTENSION` reports
the capability to be present.
`flags` must currently be zero.
.. _kvm_run:
5. The kvm_run structure
6523-7323Application은 vCPU fd를 `mmap()`해 `struct kvm_run` 포인터를 얻습니다. `KVM_RUN` 전에 입력 field를 바꾸어 실행을 제어하고, 반환 뒤 `exit_reason`과 union member를 읽어 userspace 처리가 필요한 원인을 확인합니다.
Field의미
`request_interrupt_window`외부 interrupt를 주입할 수 있게 되면 `KVM_RUN` 반환 요청
`immediate_exit`시작 시 한 번 검사하며 0이 아니면 즉시 `-EINTR`; signal handler 기반 vCPU kick에 사용
`exit_reason``KVM_RUN`이 0을 반환했을 때의 VM exit 원인
`ready_for_interrupt_injection`요청한 interrupt window가 열렸음을 표시
`if_flag`in-kernel local APIC이 없을 때 현재 interrupt flag
`flags`x86 SMM·bus lock·nested guest mode 또는 arm64 debug HSR-high 유효 상태
`cr8`in-kernel local APIC이 없을 때 양방향 CR8 값
`apic_base`in-kernel local APIC이 없을 때 양방향 APIC BASE MSR 값
In/out 방향과 유효 조건을 함께 확인해야 합니다.
`immediate_exit`는 `KVM_CAP_IMMEDIATE_EXIT`가 없으면 무시됩니다. signal을 `KVM_RUN` 밖에서 block하고 `KVM_SET_SIGNAL_MASK`를 쓰는 방식보다 확장성이 좋은 vCPU 중단 경로를 만들 수 있습니다.
ExitPayload와 처리
`KVM_EXIT_UNKNOWN``hardware_exit_reason`에 architecture별 미확인 원인
`KVM_EXIT_FAIL_ENTRY`실행 진입 실패 원인과 `KVM_LAST_CPU` 사용 시 CPU 번호
`KVM_EXIT_EXCEPTION`현재 미사용
`KVM_EXIT_IO`port I/O 방향·byte 크기·port·반복 수·packed data offset
`KVM_EXIT_DEBUG``kvm_debug_exit_arch`의 architecture별 debug event 정보
`KVM_EXIT_MMIO`물리 주소, 최대 8바이트 data, 길이와 write 여부
Union에서 exit reason에 대응하는 member만 해석합니다.
`KVM_EXIT_IO_OUT`에서는 `data_offset`이 guest 출력 data 위치이고 `KVM_EXIT_IO_IN`에서는 다음 `KVM_RUN` 전에 userspace가 입력 data를 써야 할 위치입니다. Data는 packed array입니다.
`KVM_EXIT_MMIO`의 `data[0..len)`은 vCPU가 같은 폭으로 byte array에 직접 load/store했을 때 보일 byte 순서입니다. Write이면 이미 값이 들어 있고 read이면 userspace가 채웁니다.
`KVM_EXIT_IO`, `MMIO`, `OSI`, `PAPR`, `XEN`, `EPR`, `HYPERCALL`, `TDX`, `X86_RDMSR`, `X86_WRMSR` 작업은 userspace가 다시 `KVM_RUN`으로 kernel에 들어가야 guest state까지 일관되게 완료됩니다.
Pending operation은 userspace에 보이는 state에 저장되지 않으므로 live migration 전에 반드시 완료해야 합니다. Unmasked signal pending 또는 `immediate_exit`를 설정한 채 재진입하면 추가 guest instruction 없이 pending 작업만 마칠 수 있습니다.
Host userspace와 guest 상호작용 기능은 x86에서 `KVM_EXIT_IO`, s390을 제외한 architecture에서 `KVM_EXIT_MMIO` 사용을 강하게 권장합니다. x86 port I/O exit가 MMIO exit보다 상당히 빠릅니다.
`KVM_EXIT_HYPERCALL`은 번호, 최대 6개 argument, 반환값과 flags를 제공합니다. arm64 SMCCC filter가 허용한 호출에서는 `nr`이 function ID이고 argument는 `KVM_GET_ONE_REG`으로 GPR에서 읽습니다.
Flag의미
`KVM_HYPERCALL_EXIT_SMC`SMC conduit 사용; clear이면 HVC conduit
`KVM_HYPERCALL_EXIT_16BIT`16비트 instruction 사용; clear이면 32비트이며 AArch64에서는 항상 clear
Trap 직후 PC는 trapping instruction 다음을 가리킵니다.
`KVM_EXIT_TPR_ACCESS`는 `rip`와 write 여부를 전달하며 `KVM_TPR_ACCESS_REPORTING`용이지만 상세 계약은 아직 문서화되지 않았습니다.
Exit의미
`KVM_EXIT_S390_SIEIC`interception code, PSW mask·address, IPA와 IPB
`KVM_EXIT_S390_RESET`POR, CLEAR, SUBSYSTEM, CPU_INIT, IPL reset flag
`KVM_EXIT_S390_UCONTROL`kernel이 해결하지 못한 userspace-controlled VM host page-table fault의 program·translation code
`KVM_EXIT_S390_TSCH`TEST SUBCHANNEL interception과 dequeue된 pending I/O interrupt 정보
s390 전용 interception과 reset 정보를 전달합니다.
`KVM_EXIT_DCR`은 과거 PowerPC 440 KVM에서 쓰던 deprecated exit입니다. `KVM_EXIT_OSI`는 MOL의 OSI hypercall에 32개 GPR을 전달하고, userspace가 수정하면 guest 재진입 때 전체 GPR에 반영됩니다.
`KVM_EXIT_PAPR_HCALL`은 64비트 PowerPC pSeries guest의 `sc 1` hypercall을 처리합니다. `nr`은 R3, `args[0..8]`은 R4-R12에서 오며 userspace가 `ret`과 추가 반환 argument를 채웁니다.
FSL BookE의 `KVM_EXIT_EPR`은 userspace interrupt controller가 다음 interrupt vector를 acknowledge하도록 합니다. `KVM_CAP_PPC_EPR`가 enable되고 external interrupt가 전달된 직후 발생하며 userspace가 `epr`에 vector를 씁니다.
TypeUserspace 의미
`KVM_SYSTEM_EVENT_SHUTDOWN`guest 종료 요청; 무시하거나 비동기 종료 가능
`KVM_SYSTEM_EVENT_RESET`guest reset 요청; 무시하거나 이후 reset 예약 가능
`KVM_SYSTEM_EVENT_CRASH`crash 상태 유지 요청; dump, reset 또는 종료 선택
`KVM_SYSTEM_EVENT_WAKEUP`suspended vCPU wakeup 감지; runnable 처리하거나 거부
`KVM_SYSTEM_EVENT_SUSPEND`VM suspend 요청
`KVM_SYSTEM_EVENT_SEV_TERM`AMD SEV guest 종료 요청; GHCB GPA는 `data[0]`
`KVM_SYSTEM_EVENT_TDX_FATAL`TDX fatal 상태와 instruction encoding index 순서의 16개 GPR
Architecture별 hypercall 또는 특수 instruction이 만든 system-level event입니다.
`KVM_CAP_SYSTEM_EVENT_DATA`가 있으면 `data[0..ndata)`만 유효합니다. arm64 PSCI RESET2·OFF2 flag와 RISC-V `sbi_system_reset` 두 번째 argument 같은 architecture별 정보가 들어갑니다. 과거 `flags` field는 현재 `data[0]` alias입니다.
arm/arm64의 PSCI `SYSTEM_SUSPEND` exit는 `KVM_CAP_ARM_SYSTEM_SUSPEND`로 enable합니다. KVM은 vCPU state를 바꾸지 않으므로 userspace가 register에 남은 argument를 해석해 suspend를 수행하거나 허용된 반환값으로 거부해야 합니다.
Suspend를 수락할 때 호출 vCPU를 `KVM_MP_STATE_SUSPENDED`로 설정해 in-kernel emulation을 요청할 수 있으며 resume 시 PSCI parameter에 맞춰 vCPU state를 구성해야 합니다.
PSCI v1.3 `SYSTEM_OFF2`의 지원 hibernate type은 `HIBERNATE_OFF`뿐이며 `KVM_SYSTEM_EVENT_SHUTDOWN`과 `KVM_SYSTEM_EVENT_SHUTDOWN_FLAG_PSCI_OFF2`로 전달됩니다.
`KVM_EXIT_IOAPIC_EOI`는 split irqchip에서 in-kernel local APIC이 level-triggered IOAPIC interrupt의 EOI를 받았음을 알립니다. Userspace IOAPIC은 vector를 처리하고 여전히 asserted이면 interrupt를 다시 trigger합니다.
Type동작
`KVM_EXIT_HYPERV_SYNIC`SynIC event·message page remap과 userspace 처리 enable 상태 갱신
`KVM_EXIT_HYPERV_HCALL`Hyper-V hypercall input, result와 parameter 처리
`KVM_EXIT_HYPERV_SYNDBG`synthetic debugger pending page 갱신 또는 send/receive control command
Hyper-V emulation 관련 동기 userspace 처리를 요청합니다.
arm64 `KVM_EXIT_ARM_NISV`는 memslot 밖 접근을 MMIO로 처리하려 하지만 instruction decode 정보가 없는 경우의 exit입니다. `esr_iss`에 ESR_EL2 유효 bit, `fault_ipa`에 fault address를 제공합니다.
Userspace는 `KVM_CAP_ARM_NISV_TO_USER`를 VM 생성 시 enable한 뒤 instruction을 직접 decode해 I/O를 emulate하거나 VM suspend·dump·restart를 선택할 수 있습니다. KVM은 MMIO exit와 달리 fault instruction을 건너뛰지 않습니다.
Protected VM은 emulation에 필요한 state를 userspace가 볼 수 없어 NISV-to-user를 지원하지 않고 guest에 data abort를 직접 주입합니다. System 범위 capability가 보여도 protected VM fd에서는 노출되지 않습니다.
항목의미
`KVM_EXIT_X86_RDMSR``index` MSR의 read 값을 `data`에 쓰고 재진입; 실패면 `error=1`로 `#GP` 주입
`KVM_EXIT_X86_WRMSR``index`와 `data` write 처리 뒤 재진입; 실패면 `error=1`
`KVM_MSR_EXIT_REASON_UNKNOWN`KVM이 모르는 MSR
`KVM_MSR_EXIT_REASON_INVAL`유효하지 않은 MSR 또는 reserved bit 접근
`KVM_MSR_EXIT_REASON_FILTER``KVM_X86_SET_MSR_FILTER`가 차단한 접근
`KVM_CAP_X86_USER_SPACE_MSR`와 enable한 reason에 대해서만 발생합니다.
`KVM_EXIT_XEN`의 `KVM_EXIT_XEN_HCALL`은 Xen hypercall의 long mode, CPL, input, 최대 6개 parameter와 result를 전달합니다. Userspace가 결과를 채운 뒤 `KVM_RUN`을 다시 호출합니다.
`KVM_EXIT_RISCV_SBI`는 KVM RISC-V module이 처리하지 않은 SBI call입니다. `extension_id`, `function_id`, 여섯 argument와 두 반환값을 제공하며 userspace가 반환값을 갱신한 뒤 vCPU를 resume합니다.
`KVM_EXIT_MEMORY_FAULT`는 KVM이 해결할 수 없는 `[gpa, gpa+size)` memory fault입니다. `KVM_MEMORY_EXIT_FLAG_PRIVATE`가 set이면 private, clear이면 shared access입니다.
Memory-fault exit만은 다른 exit와 달리 `KVM_RUN` 반환값이 0이 아니라 -1이고 errno는 `EFAULT` 또는 `EHWPOISON`입니다. 다른 errno에서는 `kvm_run.exit_reason`이 stale 또는 undefined라고 가정해야 합니다.
x86 `KVM_EXIT_NOTIFY`는 `KVM_CAP_X86_NOTIFY_VMEXIT`와 userspace notification을 enable했을 때 지정 시간 동안 non-root mode event window가 없으면 발생합니다. `KVM_NOTIFY_CONTEXT_INVALID`이면 VMCS context가 손상되어 resume 결과가 정의되지 않습니다.
`KVM_EXIT_TDX`는 GHCI가 정한 일부 TDVMCALL을 최소 변환으로 userspace VMM에 전달합니다. `flags`는 현재 0이고 `nr`은 R11의 TDVMCALL 번호이며 union에 입력과 출력이 있습니다.
nr처리
`TDVMCALL_GET_QUOTE`shared GPA·size buffer의 TD Report를 quoting enclave에 보내고 같은 buffer로 Quote 반환
`TDVMCALL_GET_TD_VM_CALL_INFO`요청 leaf의 지원 정보를 `r11`부터 `r14`에 기록
`TDVMCALL_SETUP_EVENT_NOTIFY_INTERRUPT`지정 vector의 notification interrupt 구성
지원하지 않는 call은 일반적으로 `unknown.ret`에 unsupported 상태가 미리 설정됩니다.
KVM은 별도 capability enable 없이도 향후 새 TDVMCALL exit를 추가할 수 있습니다. Userspace가 지원하지 않으면 아무 작업 없이 재진입할 수 있고 미지원 반환값이 guest에 전달됩니다.
Union은 `padding[256]`으로 ABI 크기를 고정합니다. 뒤의 `kvm_valid_regs`, `kvm_dirty_regs`, `struct kvm_sync_regs`는 `KVM_CAP_SYNC_REGS`가 있을 때 별도 GET/SET register ioctl 없이 register group을 교환해 syscall overhead를 줄입니다.
Userspace는 architecture별 `kvm_valid_regs` bit로 동기 영역의 유효성을 확인하고 수정한 group을 `kvm_dirty_regs`에 표시합니다. 다만 kernel이 특정 register type의 주 저장소로 `kvm_run`을 쓸 수 있으므로 dirty bit가 없어도 그 값을 사용할 수 있습니다.
5. The kvm_run structure
========================
Application code obtains a pointer to the kvm_run structure by
mmap()ing a vcpu fd. From that point, application code can control
execution by changing fields in kvm_run prior to calling the KVM_RUN
ioctl, and obtain information about the reason KVM_RUN returned by
looking up structure members.
::
struct kvm_run {
/* in */
__u8 request_interrupt_window;
Request that KVM_RUN return when it becomes possible to inject external
interrupts into the guest. Useful in conjunction with KVM_INTERRUPT.
::
__u8 immediate_exit;
This field is polled once when KVM_RUN starts; if non-zero, KVM_RUN
exits immediately, returning -EINTR. In the common scenario where a
signal is used to "kick" a VCPU out of KVM_RUN, this field can be used
to avoid usage of KVM_SET_SIGNAL_MASK, which has worse scalability.
Rather than blocking the signal outside KVM_RUN, userspace can set up
a signal handler that sets run->immediate_exit to a non-zero value.
This field is ignored if KVM_CAP_IMMEDIATE_EXIT is not available.
::
__u8 padding1[6];
/* out */
__u32 exit_reason;
When KVM_RUN has returned successfully (return value 0), this informs
application code why KVM_RUN has returned. Allowable values for this
field are detailed below.
::
__u8 ready_for_interrupt_injection;
If request_interrupt_window has been specified, this field indicates
an interrupt can be injected now with KVM_INTERRUPT.
::
__u8 if_flag;
The value of the current interrupt flag. Only valid if in-kernel
local APIC is not used.
::
__u16 flags;
More architecture-specific flags detailing state of the VCPU that may
affect the device's behavior. Current defined flags::
/* x86, set if the VCPU is in system management mode */
#define KVM_RUN_X86_SMM (1 << 0)
/* x86, set if bus lock detected in VM */
#define KVM_RUN_X86_BUS_LOCK (1 << 1)
/* x86, set if the VCPU is executing a nested (L2) guest */
#define KVM_RUN_X86_GUEST_MODE (1 << 2)
/* arm64, set for KVM_EXIT_DEBUG */
#define KVM_DEBUG_ARCH_HSR_HIGH_VALID (1 << 0)
::
/* in (pre_kvm_run), out (post_kvm_run) */
__u64 cr8;
The value of the cr8 register. Only valid if in-kernel local APIC is
not used. Both input and output.
::
__u64 apic_base;
The value of the APIC BASE msr. Only valid if in-kernel local
APIC is not used. Both input and output.
::
union {
/* KVM_EXIT_UNKNOWN */
struct {
__u64 hardware_exit_reason;
} hw;
If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown
reasons. Further architecture-specific information is available in
hardware_exit_reason.
::
/* KVM_EXIT_FAIL_ENTRY */
struct {
__u64 hardware_entry_failure_reason;
__u32 cpu; /* if KVM_LAST_CPU */
} fail_entry;
If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due
to unknown reasons. Further architecture-specific information is
available in hardware_entry_failure_reason.
::
/* KVM_EXIT_EXCEPTION */
struct {
__u32 exception;
__u32 error_code;
} ex;
Unused.
::
/* KVM_EXIT_IO */
struct {
#define KVM_EXIT_IO_IN 0
#define KVM_EXIT_IO_OUT 1
__u8 direction;
__u8 size; /* bytes */
__u16 port;
__u32 count;
__u64 data_offset; /* relative to kvm_run start */
} io;
If exit_reason is KVM_EXIT_IO, then the vcpu has
executed a port I/O instruction which could not be satisfied by kvm.
data_offset describes where the data is located (KVM_EXIT_IO_OUT) or
where kvm expects application code to place the data for the next
KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a packed array.
::
/* KVM_EXIT_DEBUG */
struct {
struct kvm_debug_exit_arch arch;
} debug;
If the exit_reason is KVM_EXIT_DEBUG, then a vcpu is processing a debug event
for which architecture specific information is returned.
::
/* KVM_EXIT_MMIO */
struct {
__u64 phys_addr;
__u8 data[8];
__u32 len;
__u8 is_write;
} mmio;
If exit_reason is KVM_EXIT_MMIO, then the vcpu has
executed a memory-mapped I/O instruction which could not be satisfied
by kvm. The 'data' member contains the written data if 'is_write' is
true, and should be filled by application code otherwise.
The 'data' member contains, in its first 'len' bytes, the value as it would
appear if the VCPU performed a load or store of the appropriate width directly
to the byte array.
.. note::
For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR, KVM_EXIT_XEN,
KVM_EXIT_EPR, KVM_EXIT_HYPERCALL, KVM_EXIT_TDX,
KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR the corresponding
operations are complete (and guest state is consistent) only after userspace
has re-entered the kernel with KVM_RUN. The kernel side will first finish
incomplete operations and then check for pending signals.
The pending state of the operation is not preserved in state which is
visible to userspace, thus userspace should ensure that the operation is
completed before performing a live migration. Userspace can re-enter the
guest with an unmasked signal pending or with the immediate_exit field set
to complete pending operations without allowing any further instructions
to be executed.
::
/* KVM_EXIT_HYPERCALL */
struct {
__u64 nr;
__u64 args[6];
__u64 ret;
__u64 flags;
} hypercall;
It is strongly recommended that userspace use ``KVM_EXIT_IO`` (x86) or
``KVM_EXIT_MMIO`` (all except s390) to implement functionality that
requires a guest to interact with host userspace.
.. note:: KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
For arm64:
----------
SMCCC exits can be enabled depending on the configuration of the SMCCC
filter. See the Documentation/virt/kvm/devices/vm.rst
``KVM_ARM_SMCCC_FILTER`` for more details.
``nr`` contains the function ID of the guest's SMCCC call. Userspace is
expected to use the ``KVM_GET_ONE_REG`` ioctl to retrieve the call
parameters from the vCPU's GPRs.
Definition of ``flags``:
- ``KVM_HYPERCALL_EXIT_SMC``: Indicates that the guest used the SMC
conduit to initiate the SMCCC call. If this bit is 0 then the guest
used the HVC conduit for the SMCCC call.
- ``KVM_HYPERCALL_EXIT_16BIT``: Indicates that the guest used a 16bit
instruction to initiate the SMCCC call. If this bit is 0 then the
guest used a 32bit instruction. An AArch64 guest always has this
bit set to 0.
At the point of exit, PC points to the instruction immediately following
the trapping instruction.
::
/* KVM_EXIT_TPR_ACCESS */
struct {
__u64 rip;
__u32 is_write;
__u32 pad;
} tpr_access;
To be documented (KVM_TPR_ACCESS_REPORTING).
::
/* KVM_EXIT_S390_SIEIC */
struct {
__u8 icptcode;
__u64 mask; /* psw upper half */
__u64 addr; /* psw lower half */
__u16 ipa;
__u32 ipb;
} s390_sieic;
s390 specific.
::
/* KVM_EXIT_S390_RESET */
#define KVM_S390_RESET_POR 1
#define KVM_S390_RESET_CLEAR 2
#define KVM_S390_RESET_SUBSYSTEM 4
#define KVM_S390_RESET_CPU_INIT 8
#define KVM_S390_RESET_IPL 16
__u64 s390_reset_flags;
s390 specific.
::
/* KVM_EXIT_S390_UCONTROL */
struct {
__u64 trans_exc_code;
__u32 pgm_code;
} s390_ucontrol;
s390 specific. A page fault has occurred for a user controlled virtual
machine (KVM_VM_S390_UNCONTROL) on its host page table that cannot be
resolved by the kernel.
The program code and the translation exception code that were placed
in the cpu's lowcore are presented here as defined by the z Architecture
Principles of Operation Book in the Chapter for Dynamic Address Translation
(DAT)
::
/* KVM_EXIT_DCR */
struct {
__u32 dcrn;
__u32 data;
__u8 is_write;
} dcr;
Deprecated - was used for 440 KVM.
::
/* KVM_EXIT_OSI */
struct {
__u64 gprs[32];
} osi;
MOL uses a special hypercall interface it calls 'OSI'. To enable it, we catch
hypercalls and exit with this exit struct that contains all the guest gprs.
If exit_reason is KVM_EXIT_OSI, then the vcpu has triggered such a hypercall.
Userspace can now handle the hypercall and when it's done modify the gprs as
necessary. Upon guest entry all guest GPRs will then be replaced by the values
in this struct.
::
/* KVM_EXIT_PAPR_HCALL */
struct {
__u64 nr;
__u64 ret;
__u64 args[9];
} papr_hcall;
This is used on 64-bit PowerPC when emulating a pSeries partition,
e.g. with the 'pseries' machine type in qemu. It occurs when the
guest does a hypercall using the 'sc 1' instruction. The 'nr' field
contains the hypercall number (from the guest R3), and 'args' contains
the arguments (from the guest R4 - R12). Userspace should put the
return code in 'ret' and any extra returned values in args[].
The possible hypercalls are defined in the Power Architecture Platform
Requirements (PAPR) document available from www.power.org (free
developer registration required to access it).
::
/* KVM_EXIT_S390_TSCH */
struct {
__u16 subchannel_id;
__u16 subchannel_nr;
__u32 io_int_parm;
__u32 io_int_word;
__u32 ipb;
__u8 dequeued;
} s390_tsch;
s390 specific. This exit occurs when KVM_CAP_S390_CSS_SUPPORT has been enabled
and TEST SUBCHANNEL was intercepted. If dequeued is set, a pending I/O
interrupt for the target subchannel has been dequeued and subchannel_id,
subchannel_nr, io_int_parm and io_int_word contain the parameters for that
interrupt. ipb is needed for instruction parameter decoding.
::
/* KVM_EXIT_EPR */
struct {
__u32 epr;
} epr;
On FSL BookE PowerPC chips, the interrupt controller has a fast patch
interrupt acknowledge path to the core. When the core successfully
delivers an interrupt, it automatically populates the EPR register with
the interrupt vector number and acknowledges the interrupt inside
the interrupt controller.
In case the interrupt controller lives in user space, we need to do
the interrupt acknowledge cycle through it to fetch the next to be
delivered interrupt vector using this exit.
It gets triggered whenever both KVM_CAP_PPC_EPR are enabled and an
external interrupt has just been delivered into the guest. User space
should put the acknowledged interrupt vector into the 'epr' field.
::
/* KVM_EXIT_SYSTEM_EVENT */
struct {
#define KVM_SYSTEM_EVENT_SHUTDOWN 1
#define KVM_SYSTEM_EVENT_RESET 2
#define KVM_SYSTEM_EVENT_CRASH 3
#define KVM_SYSTEM_EVENT_WAKEUP 4
#define KVM_SYSTEM_EVENT_SUSPEND 5
#define KVM_SYSTEM_EVENT_SEV_TERM 6
#define KVM_SYSTEM_EVENT_TDX_FATAL 7
__u32 type;
__u32 ndata;
__u64 data[16];
} system_event;
If exit_reason is KVM_EXIT_SYSTEM_EVENT then the vcpu has triggered
a system-level event using some architecture specific mechanism (hypercall
or some special instruction). In case of ARM64, this is triggered using
HVC instruction based PSCI call from the vcpu.
The 'type' field describes the system-level event type.
Valid values for 'type' are:
- KVM_SYSTEM_EVENT_SHUTDOWN -- the guest has requested a shutdown of the
VM. Userspace is not obliged to honour this, and if it does honour
this does not need to destroy the VM synchronously (ie it may call
KVM_RUN again before shutdown finally occurs).
- KVM_SYSTEM_EVENT_RESET -- the guest has requested a reset of the VM.
As with SHUTDOWN, userspace can choose to ignore the request, or
to schedule the reset to occur in the future and may call KVM_RUN again.
- KVM_SYSTEM_EVENT_CRASH -- the guest crash occurred and the guest
has requested a crash condition maintenance. Userspace can choose
to ignore the request, or to gather VM memory core dump and/or
reset/shutdown of the VM.
- KVM_SYSTEM_EVENT_SEV_TERM -- an AMD SEV guest requested termination.
The guest physical address of the guest's GHCB is stored in `data[0]`.
- KVM_SYSTEM_EVENT_TDX_FATAL -- a TDX guest reported a fatal error state.
KVM doesn't do any parsing or conversion, it just dumps 16 general-purpose
registers to userspace, in ascending order of the 4-bit indices for x86-64
general-purpose registers in instruction encoding, as defined in the Intel
SDM.
- KVM_SYSTEM_EVENT_WAKEUP -- the exiting vCPU is in a suspended state and
KVM has recognized a wakeup event. Userspace may honor this event by
marking the exiting vCPU as runnable, or deny it and call KVM_RUN again.
- KVM_SYSTEM_EVENT_SUSPEND -- the guest has requested a suspension of
the VM.
If KVM_CAP_SYSTEM_EVENT_DATA is present, the 'data' field can contain
architecture specific information for the system-level event. Only
the first `ndata` items (possibly zero) of the data array are valid.
- for arm64, data[0] is set to KVM_SYSTEM_EVENT_RESET_FLAG_PSCI_RESET2 if
the guest issued a SYSTEM_RESET2 call according to v1.1 of the PSCI
specification.
- for arm64, data[0] is set to KVM_SYSTEM_EVENT_SHUTDOWN_FLAG_PSCI_OFF2
if the guest issued a SYSTEM_OFF2 call according to v1.3 of the PSCI
specification.
- for RISC-V, data[0] is set to the value of the second argument of the
``sbi_system_reset`` call.
Previous versions of Linux defined a `flags` member in this struct. The
field is now aliased to `data[0]`. Userspace can assume that it is only
written if ndata is greater than 0.
For arm/arm64:
--------------
KVM_SYSTEM_EVENT_SUSPEND exits are enabled with the
KVM_CAP_ARM_SYSTEM_SUSPEND VM capability. If a guest invokes the PSCI
SYSTEM_SUSPEND function, KVM will exit to userspace with this event
type.
It is the sole responsibility of userspace to implement the PSCI
SYSTEM_SUSPEND call according to ARM DEN0022D.b 5.19 "SYSTEM_SUSPEND".
KVM does not change the vCPU's state before exiting to userspace, so
the call parameters are left in-place in the vCPU registers.
Userspace is _required_ to take action for such an exit. It must
either:
- Honor the guest request to suspend the VM. Userspace can request
in-kernel emulation of suspension by setting the calling vCPU's
state to KVM_MP_STATE_SUSPENDED. Userspace must configure the vCPU's
state according to the parameters passed to the PSCI function when
the calling vCPU is resumed. See ARM DEN0022D.b 5.19.1 "Intended use"
for details on the function parameters.
- Deny the guest request to suspend the VM. See ARM DEN0022D.b 5.19.2
"Caller responsibilities" for possible return values.
Hibernation using the PSCI SYSTEM_OFF2 call is enabled when PSCI v1.3
is enabled. If a guest invokes the PSCI SYSTEM_OFF2 function, KVM will
exit to userspace with the KVM_SYSTEM_EVENT_SHUTDOWN event type and with
data[0] set to KVM_SYSTEM_EVENT_SHUTDOWN_FLAG_PSCI_OFF2. The only
supported hibernate type for the SYSTEM_OFF2 function is HIBERNATE_OFF.
::
/* KVM_EXIT_IOAPIC_EOI */
struct {
__u8 vector;
} eoi;
Indicates that the VCPU's in-kernel local APIC received an EOI for a
level-triggered IOAPIC interrupt. This exit only triggers when the
IOAPIC is implemented in userspace (i.e. KVM_CAP_SPLIT_IRQCHIP is enabled);
the userspace IOAPIC should process the EOI and retrigger the interrupt if
it is still asserted. Vector is the LAPIC interrupt vector for which the
EOI was received.
::
struct kvm_hyperv_exit {
#define KVM_EXIT_HYPERV_SYNIC 1
#define KVM_EXIT_HYPERV_HCALL 2
#define KVM_EXIT_HYPERV_SYNDBG 3
__u32 type;
__u32 pad1;
union {
struct {
__u32 msr;
__u32 pad2;
__u64 control;
__u64 evt_page;
__u64 msg_page;
} synic;
struct {
__u64 input;
__u64 result;
__u64 params[2];
} hcall;
struct {
__u32 msr;
__u32 pad2;
__u64 control;
__u64 status;
__u64 send_page;
__u64 recv_page;
__u64 pending_page;
} syndbg;
} u;
};
/* KVM_EXIT_HYPERV */
struct kvm_hyperv_exit hyperv;
Indicates that the VCPU exits into userspace to process some tasks
related to Hyper-V emulation.
Valid values for 'type' are:
- KVM_EXIT_HYPERV_SYNIC -- synchronously notify user-space about
Hyper-V SynIC state change. Notification is used to remap SynIC
event/message pages and to enable/disable SynIC messages/events processing
in userspace.
- KVM_EXIT_HYPERV_SYNDBG -- synchronously notify user-space about
Hyper-V Synthetic debugger state change. Notification is used to either update
the pending_page location or to send a control command (send the buffer located
in send_page or recv a buffer to recv_page).
::
/* KVM_EXIT_ARM_NISV */
struct {
__u64 esr_iss;
__u64 fault_ipa;
} arm_nisv;
Used on arm64 systems. If a guest accesses memory not in a memslot,
KVM will typically return to userspace and ask it to do MMIO emulation on its
behalf. However, for certain classes of instructions, no instruction decode
(direction, length of memory access) is provided, and fetching and decoding
the instruction from the VM is overly complicated to live in the kernel.
Historically, when this situation occurred, KVM would print a warning and kill
the VM. KVM assumed that if the guest accessed non-memslot memory, it was
trying to do I/O, which just couldn't be emulated, and the warning message was
phrased accordingly. However, what happened more often was that a guest bug
caused access outside the guest memory areas which should lead to a more
meaningful warning message and an external abort in the guest, if the access
did not fall within an I/O window.
Userspace implementations can query for KVM_CAP_ARM_NISV_TO_USER, and enable
this capability at VM creation. Once this is done, these types of errors will
instead return to userspace with KVM_EXIT_ARM_NISV, with the valid bits from
the ESR_EL2 in the esr_iss field, and the faulting IPA in the fault_ipa field.
Userspace can either fix up the access if it's actually an I/O access by
decoding the instruction from guest memory (if it's very brave) and continue
executing the guest, or it can decide to suspend, dump, or restart the guest.
Note that KVM does not skip the faulting instruction as it does for
KVM_EXIT_MMIO, but userspace has to emulate any change to the processing state
if it decides to decode and emulate the instruction.
This feature isn't available to protected VMs, as userspace does not
have access to the state that is required to perform the emulation.
Instead, a data abort exception is directly injected in the guest.
Note that although KVM_CAP_ARM_NISV_TO_USER will be reported if
queried outside of a protected VM context, the feature will not be
exposed if queried on a protected VM file descriptor.
::
/* KVM_EXIT_X86_RDMSR / KVM_EXIT_X86_WRMSR */
struct {
__u8 error; /* user -> kernel */
__u8 pad[7];
__u32 reason; /* kernel -> user */
__u32 index; /* kernel -> user */
__u64 data; /* kernel <-> user */
} msr;
Used on x86 systems. When the VM capability KVM_CAP_X86_USER_SPACE_MSR is
enabled, MSR accesses to registers that would invoke a #GP by KVM kernel code
may instead trigger a KVM_EXIT_X86_RDMSR exit for reads and KVM_EXIT_X86_WRMSR
exit for writes.
The "reason" field specifies why the MSR interception occurred. Userspace will
only receive MSR exits when a particular reason was requested during through
ENABLE_CAP. Currently valid exit reasons are:
============================ ========================================
KVM_MSR_EXIT_REASON_UNKNOWN access to MSR that is unknown to KVM
KVM_MSR_EXIT_REASON_INVAL access to invalid MSRs or reserved bits
KVM_MSR_EXIT_REASON_FILTER access blocked by KVM_X86_SET_MSR_FILTER
============================ ========================================
For KVM_EXIT_X86_RDMSR, the "index" field tells userspace which MSR the guest
wants to read. To respond to this request with a successful read, userspace
writes the respective data into the "data" field and must continue guest
execution to ensure the read data is transferred into guest register state.
If the RDMSR request was unsuccessful, userspace indicates that with a "1" in
the "error" field. This will inject a #GP into the guest when the VCPU is
executed again.
For KVM_EXIT_X86_WRMSR, the "index" field tells userspace which MSR the guest
wants to write. Once finished processing the event, userspace must continue
vCPU execution. If the MSR write was unsuccessful, userspace also sets the
"error" field to "1".
See KVM_X86_SET_MSR_FILTER for details on the interaction with MSR filtering.
::
struct kvm_xen_exit {
#define KVM_EXIT_XEN_HCALL 1
__u32 type;
union {
struct {
__u32 longmode;
__u32 cpl;
__u64 input;
__u64 result;
__u64 params[6];
} hcall;
} u;
};
/* KVM_EXIT_XEN */
struct kvm_hyperv_exit xen;
Indicates that the VCPU exits into userspace to process some tasks
related to Xen emulation.
Valid values for 'type' are:
- KVM_EXIT_XEN_HCALL -- synchronously notify user-space about Xen hypercall.
Userspace is expected to place the hypercall result into the appropriate
field before invoking KVM_RUN again.
::
/* KVM_EXIT_RISCV_SBI */
struct {
unsigned long extension_id;
unsigned long function_id;
unsigned long args[6];
unsigned long ret[2];
} riscv_sbi;
If exit reason is KVM_EXIT_RISCV_SBI then it indicates that the VCPU has
done a SBI call which is not handled by KVM RISC-V kernel module. The details
of the SBI call are available in 'riscv_sbi' member of kvm_run structure. The
'extension_id' field of 'riscv_sbi' represents SBI extension ID whereas the
'function_id' field represents function ID of given SBI extension. The 'args'
array field of 'riscv_sbi' represents parameters for the SBI call and 'ret'
array field represents return values. The userspace should update the return
values of SBI call before resuming the VCPU. For more details on RISC-V SBI
spec refer, https://github.com/riscv/riscv-sbi-doc.
::
/* KVM_EXIT_MEMORY_FAULT */
struct {
#define KVM_MEMORY_EXIT_FLAG_PRIVATE (1ULL << 3)
__u64 flags;
__u64 gpa;
__u64 size;
} memory_fault;
KVM_EXIT_MEMORY_FAULT indicates the vCPU has encountered a memory fault that
could not be resolved by KVM. The 'gpa' and 'size' (in bytes) describe the
guest physical address range [gpa, gpa + size) of the fault. The 'flags' field
describes properties of the faulting access that are likely pertinent:
- KVM_MEMORY_EXIT_FLAG_PRIVATE - When set, indicates the memory fault occurred
on a private memory access. When clear, indicates the fault occurred on a
shared access.
Note! KVM_EXIT_MEMORY_FAULT is unique among all KVM exit reasons in that it
accompanies a return code of '-1', not '0'! errno will always be set to EFAULT
or EHWPOISON when KVM exits with KVM_EXIT_MEMORY_FAULT, userspace should assume
kvm_run.exit_reason is stale/undefined for all other error numbers.
::
/* KVM_EXIT_NOTIFY */
struct {
#define KVM_NOTIFY_CONTEXT_INVALID (1 << 0)
__u32 flags;
} notify;
Used on x86 systems. When the VM capability KVM_CAP_X86_NOTIFY_VMEXIT is
enabled, a VM exit generated if no event window occurs in VM non-root mode
for a specified amount of time. Once KVM_X86_NOTIFY_VMEXIT_USER is set when
enabling the cap, it would exit to userspace with the exit reason
KVM_EXIT_NOTIFY for further handling. The "flags" field contains more
detailed info.
The valid value for 'flags' is:
- KVM_NOTIFY_CONTEXT_INVALID -- the VM context is corrupted and not valid
in VMCS. It would run into unknown result if resume the target VM.
::
/* KVM_EXIT_TDX */
struct {
__u64 flags;
__u64 nr;
union {
struct {
u64 ret;
u64 data[5];
} unknown;
struct {
u64 ret;
u64 gpa;
u64 size;
} get_quote;
struct {
u64 ret;
u64 leaf;
u64 r11, r12, r13, r14;
} get_tdvmcall_info;
struct {
u64 ret;
u64 vector;
} setup_event_notify;
};
} tdx;
Process a TDVMCALL from the guest. KVM forwards select TDVMCALL based
on the Guest-Hypervisor Communication Interface (GHCI) specification;
KVM bridges these requests to the userspace VMM with minimal changes,
placing the inputs in the union and copying them back to the guest
on re-entry.
Flags are currently always zero, whereas ``nr`` contains the TDVMCALL
number from register R11. The remaining field of the union provide the
inputs and outputs of the TDVMCALL. Currently the following values of
``nr`` are defined:
* ``TDVMCALL_GET_QUOTE``: the guest has requested to generate a TD-Quote
signed by a service hosting TD-Quoting Enclave operating on the host.
Parameters and return value are in the ``get_quote`` field of the union.
The ``gpa`` field and ``size`` specify the guest physical address
(without the shared bit set) and the size of a shared-memory buffer, in
which the TDX guest passes a TD Report. The ``ret`` field represents
the return value of the GetQuote request. When the request has been
queued successfully, the TDX guest can poll the status field in the
shared-memory area to check whether the Quote generation is completed or
not. When completed, the generated Quote is returned via the same buffer.
* ``TDVMCALL_GET_TD_VM_CALL_INFO``: the guest has requested the support
status of TDVMCALLs. The output values for the given leaf should be
placed in fields from ``r11`` to ``r14`` of the ``get_tdvmcall_info``
field of the union.
* ``TDVMCALL_SETUP_EVENT_NOTIFY_INTERRUPT``: the guest has requested to
set up a notification interrupt for vector ``vector``.
KVM may add support for more values in the future that may cause a userspace
exit, even without calls to ``KVM_ENABLE_CAP`` or similar. In this case,
it will enter with output fields already valid; in the common case, the
``unknown.ret`` field of the union will be ``TDVMCALL_STATUS_SUBFUNC_UNSUPPORTED``.
Userspace need not do anything if it does not wish to support a TDVMCALL.
::
/* Fix the size of the union. */
char padding[256];
};
/*
* shared registers between kvm and userspace.
* kvm_valid_regs specifies the register classes set by the host
* kvm_dirty_regs specified the register classes dirtied by userspace
* struct kvm_sync_regs is architecture specific, as well as the
* bits for kvm_valid_regs and kvm_dirty_regs
*/
__u64 kvm_valid_regs;
__u64 kvm_dirty_regs;
union {
struct kvm_sync_regs regs;
char padding[SYNC_REGS_SIZE_BYTES];
} s;
If KVM_CAP_SYNC_REGS is defined, these fields allow userspace to access
certain guest registers without having to call SET/GET_*REGS. Thus we can
avoid some system call overhead if userspace has to handle the exit.
Userspace can query the validity of the structure by checking
kvm_valid_regs for specific bits. These bits are architecture specific
and usually define the validity of a groups of registers. (e.g. one bit
for general purpose registers)
Please note that the kernel is allowed to use the kvm_run structure as the
primary storage for certain register types. Therefore, the kernel may use the
values in kvm_run even if the corresponding bit in kvm_dirty_regs is not set.
.. _cap_enable:
6. Capabilities that can be enabled on vCPUs
7324-7655일부 capability는 `KVM_ENABLE_CAP`으로 활성화했을 때 vCPU 또는 VM의 동작을 바꿉니다. 각 항목은 지원 architecture, vCPU·VM target, argument와 capability 고유 반환값을 정의합니다.
Capability효과
`KVM_CAP_PPC_OSI`Mac-on-Linux OSI hypercall을 intercept해 `KVM_EXIT_OSI` 발생
`KVM_CAP_PPC_PAPR``sc 1` PAPR hypercall intercept, supervisor mode와 HVA 기반 SDR1 HTAB 의미 활성화
`KVM_CAP_SW_TLB`Userspace·KVM 공유 software TLB array 구성
`KVM_CAP_PPC_EPR`external proxy interrupt 전달을 enable/disable하고 enable 시 `KVM_EXIT_EPR` 발생
`KVM_CAP_IRQ_MPIC`vCPU를 in-kernel MPIC fd와 CPU 번호에 연결
`KVM_CAP_IRQ_XICS`vCPU를 in-kernel XICS fd와 server ID에 연결
`KVM_CAP_PPC_IRQ_XIVE`vCPU를 in-kernel XIVE fd와 server ID에 연결
Hypercall interception, software TLB와 interrupt-controller 연결을 구성합니다.
PAPR mode에서는 guest privilege가 보통 hypervisor가 아닌 supervisor가 되고, guest에 숨겨진 HTAB 때문에 SDR1의 HTAB 주소 부분이 GPA 대신 HVA를 담습니다.
`KVM_CAP_SW_TLB`의 `params`와 `array`는 MMU type별 userspace 구조 주소이고 `array_len`은 예약한 byte 수입니다. `KVM_RUN` 중 공유 영역은 KVM 소유라 userspace가 수정하면 제한된 범위에서 정의되지 않은 동작이 됩니다.
`KVM_RUN` 반환 뒤 array는 현재 guest TLB를 반영합니다. Userspace가 entry를 바꾸면 같은 vCPU를 다시 실행하기 전에 `KVM_DIRTY_TLB`로 변경 entry를 알려야 합니다.
FSL BookE NOHV·HV MMU에서 `params`는 `kvm_book3e_206_tlb_params`, `array`는 `kvm_book3e_206_tlb_entry` 배열입니다. TLB0 다음 TLB1 순서이고 각 TLB 안에서는 set, ESEL 순입니다.
TLB0 set hash는 `(MAS2 >> 12) & (num_sets - 1)`이고 `num_sets`는 `tlb_sizes[] / tlb_ways[]`입니다. Hardware가 무시하더라도 TLB0의 `mas1.tsize`는 4K로 설정해야 합니다.
Capability효과
`KVM_CAP_S390_CSS_SUPPORT`channel I/O 지원; TEST PENDING INTERRUPT 일부는 kernel, 나머지는 userspace, TSCH intercept는 `KVM_EXIT_S390_TSCH`
`KVM_CAP_S390_IRQCHIP`s390 VM의 in-kernel irqchip 활성화
`KVM_CAP_MIPS_FPU`host FPU를 guest에 허용하고 FPR·FCR, Status.FR과 Config5.FRE 접근 허용
`KVM_CAP_MIPS_MSA`MIPS SIMD Architecture와 vector·MSA register, Config5.MSAEn 접근 허용
Architecture별 execution facility를 노출합니다.
`KVM_CAP_S390_CSS_SUPPORT`는 vCPU별로 enable하지만 VM 전체에 영향을 줍니다. TEST PENDING INTERRUPTION과 TEST SUBCHANNEL의 interrupt 부분은 kernel에서 처리하고 그 밖의 I/O instruction은 userspace로 보냅니다.
MIPS FPU·MSA capability의 `args[0]`은 미래 확장용이라 0이어야 합니다. Guest register mode와 host facility 지원 여부에 따라 노출되는 register와 control bit가 달라집니다.
`KVM_CAP_SYNC_REGS`는 s390에서 항상 enable되고 x86에서는 vCPU별 capability입니다. 별도 SET/GET register ioctl 반복 없이 `kvm_run`의 sync 영역으로 register group을 교환해 userspace instruction emulation overhead를 줄입니다.
x86 `KVM_CHECK_EXTENSION`은 지원 register set bit array를 반환합니다. Userspace는 다음 exit 때 복사받을 set을 `kvm_valid_regs`에 고르고, vCPU에 되쓸 변경 set은 같은 bit flag로 `kvm_dirty_regs`에 표시해야 합니다. 미사용 bit는 0이어야 합니다.
x86 sync 구조에는 `kvm_regs`, `kvm_sregs`, `kvm_vcpu_events`가 들어갑니다. Dirty bit가 없으면 userspace가 값을 바꿔도 vCPU로 복사하지 않습니다.
Capability효과
`KVM_CAP_HYPERV_SYNIC`Windows VMBus용 SynIC 활성화; auto-EOI와 충돌하는 APIC hardware virtualization 비활성화
`KVM_CAP_HYPERV_SYNIC2`SynIC message·event flag page enable 때 KVM이 page를 clear하지 않는 새 버전
`KVM_CAP_HYPERV_DIRECT_TLBFLUSH`L0 Hyper-V가 KVM을 우회해 TLB flush hypercall 처리
`KVM_CAP_HYPERV_ENFORCE_CPUID`Hyper-V CPUID feature bit에 따라 emulated feature 제한
`KVM_CAP_ENFORCE_PV_FEATURE_CPUID``KVM_CPUID_FEATURES` leaf에 실제 노출한 bit에 따라 KVM PV feature 제한
CPUID 노출과 hypercall 처리 경로를 제한합니다.
Direct TLB flush는 Hyper-V와 KVM hypercall ABI가 달라 오인 가능성이 있으므로 KVM의 모든 hypercall 처리를 사실상 비활성화합니다. Userspace는 CPUID에서 KVM 식별을 숨기고 Hyper-V 식별만 노출해 guest가 Hyper-V hypercall만 쓰게 해야 합니다.
6. Capabilities that can be enabled on vCPUs
============================================
There are certain capabilities that change the behavior of the virtual CPU or
the virtual machine when enabled. To enable them, please see
:ref:`KVM_ENABLE_CAP`.
Below you can find a list of capabilities and what their effect on the vCPU or
the virtual machine is when enabling them.
The following information is provided along with the description:
Architectures:
which instruction set architectures provide this ioctl.
x86 includes both i386 and x86_64.
Target:
whether this is a per-vcpu or per-vm capability.
Parameters:
what parameters are accepted by the capability.
Returns:
the return value. General error numbers (EBADF, ENOMEM, EINVAL)
are not detailed, but errors with specific meanings are.
6.1 KVM_CAP_PPC_OSI
-------------------
:Architectures: ppc
:Target: vcpu
:Parameters: none
:Returns: 0 on success; -1 on error
This capability enables interception of OSI hypercalls that otherwise would
be treated as normal system calls to be injected into the guest. OSI hypercalls
were invented by Mac-on-Linux to have a standardized communication mechanism
between the guest and the host.
When this capability is enabled, KVM_EXIT_OSI can occur.
6.2 KVM_CAP_PPC_PAPR
--------------------
:Architectures: ppc
:Target: vcpu
:Parameters: none
:Returns: 0 on success; -1 on error
This capability enables interception of PAPR hypercalls. PAPR hypercalls are
done using the hypercall instruction "sc 1".
It also sets the guest privilege level to "supervisor" mode. Usually the guest
runs in "hypervisor" privilege mode with a few missing features.
In addition to the above, it changes the semantics of SDR1. In this mode, the
HTAB address part of SDR1 contains an HVA instead of a GPA, as PAPR keeps the
HTAB invisible to the guest.
When this capability is enabled, KVM_EXIT_PAPR_HCALL can occur.
6.3 KVM_CAP_SW_TLB
------------------
:Architectures: ppc
:Target: vcpu
:Parameters: args[0] is the address of a struct kvm_config_tlb
:Returns: 0 on success; -1 on error
::
struct kvm_config_tlb {
__u64 params;
__u64 array;
__u32 mmu_type;
__u32 array_len;
};
Configures the virtual CPU's TLB array, establishing a shared memory area
between userspace and KVM. The "params" and "array" fields are userspace
addresses of mmu-type-specific data structures. The "array_len" field is an
safety mechanism, and should be set to the size in bytes of the memory that
userspace has reserved for the array. It must be at least the size dictated
by "mmu_type" and "params".
While KVM_RUN is active, the shared region is under control of KVM. Its
contents are undefined, and any modification by userspace results in
boundedly undefined behavior.
On return from KVM_RUN, the shared region will reflect the current state of
the guest's TLB. If userspace makes any changes, it must call KVM_DIRTY_TLB
to tell KVM which entries have been changed, prior to calling KVM_RUN again
on this vcpu.
For mmu types KVM_MMU_FSL_BOOKE_NOHV and KVM_MMU_FSL_BOOKE_HV:
- The "params" field is of type "struct kvm_book3e_206_tlb_params".
- The "array" field points to an array of type "struct
kvm_book3e_206_tlb_entry".
- The array consists of all entries in the first TLB, followed by all
entries in the second TLB.
- Within a TLB, entries are ordered first by increasing set number. Within a
set, entries are ordered by way (increasing ESEL).
- The hash for determining set number in TLB0 is: (MAS2 >> 12) & (num_sets - 1)
where "num_sets" is the tlb_sizes[] value divided by the tlb_ways[] value.
- The tsize field of mas1 shall be set to 4K on TLB0, even though the
hardware ignores this value for TLB0.
6.4 KVM_CAP_S390_CSS_SUPPORT
----------------------------
:Architectures: s390
:Target: vcpu
:Parameters: none
:Returns: 0 on success; -1 on error
This capability enables support for handling of channel I/O instructions.
TEST PENDING INTERRUPTION and the interrupt portion of TEST SUBCHANNEL are
handled in-kernel, while the other I/O instructions are passed to userspace.
When this capability is enabled, KVM_EXIT_S390_TSCH will occur on TEST
SUBCHANNEL intercepts.
Note that even though this capability is enabled per-vcpu, the complete
virtual machine is affected.
6.5 KVM_CAP_PPC_EPR
-------------------
:Architectures: ppc
:Target: vcpu
:Parameters: args[0] defines whether the proxy facility is active
:Returns: 0 on success; -1 on error
This capability enables or disables the delivery of interrupts through the
external proxy facility.
When enabled (args[0] != 0), every time the guest gets an external interrupt
delivered, it automatically exits into user space with a KVM_EXIT_EPR exit
to receive the topmost interrupt vector.
When disabled (args[0] == 0), behavior is as if this facility is unsupported.
When this capability is enabled, KVM_EXIT_EPR can occur.
6.6 KVM_CAP_IRQ_MPIC
--------------------
:Architectures: ppc
:Parameters: args[0] is the MPIC device fd;
args[1] is the MPIC CPU number for this vcpu
This capability connects the vcpu to an in-kernel MPIC device.
6.7 KVM_CAP_IRQ_XICS
--------------------
:Architectures: ppc
:Target: vcpu
:Parameters: args[0] is the XICS device fd;
args[1] is the XICS CPU number (server ID) for this vcpu
This capability connects the vcpu to an in-kernel XICS device.
6.8 KVM_CAP_S390_IRQCHIP
------------------------
:Architectures: s390
:Target: vm
:Parameters: none
This capability enables the in-kernel irqchip for s390. Please refer to
"4.24 KVM_CREATE_IRQCHIP" for details.
6.9 KVM_CAP_MIPS_FPU
--------------------
:Architectures: mips
:Target: vcpu
:Parameters: args[0] is reserved for future use (should be 0).
This capability allows the use of the host Floating Point Unit by the guest. It
allows the Config1.FP bit to be set to enable the FPU in the guest. Once this is
done the ``KVM_REG_MIPS_FPR_*`` and ``KVM_REG_MIPS_FCR_*`` registers can be
accessed (depending on the current guest FPU register mode), and the Status.FR,
Config5.FRE bits are accessible via the KVM API and also from the guest,
depending on them being supported by the FPU.
6.10 KVM_CAP_MIPS_MSA
---------------------
:Architectures: mips
:Target: vcpu
:Parameters: args[0] is reserved for future use (should be 0).
This capability allows the use of the MIPS SIMD Architecture (MSA) by the guest.
It allows the Config3.MSAP bit to be set to enable the use of MSA by the guest.
Once this is done the ``KVM_REG_MIPS_VEC_*`` and ``KVM_REG_MIPS_MSA_*``
registers can be accessed, and the Config5.MSAEn bit is accessible via the
KVM API and also from the guest.
6.74 KVM_CAP_SYNC_REGS
----------------------
:Architectures: s390, x86
:Target: s390: always enabled, x86: vcpu
:Parameters: none
:Returns: x86: KVM_CHECK_EXTENSION returns a bit-array indicating which register
sets are supported
(bitfields defined in arch/x86/include/uapi/asm/kvm.h).
As described above in the kvm_sync_regs struct info in section :ref:`kvm_run`,
KVM_CAP_SYNC_REGS "allow[s] userspace to access certain guest registers
without having to call SET/GET_*REGS". This reduces overhead by eliminating
repeated ioctl calls for setting and/or getting register values. This is
particularly important when userspace is making synchronous guest state
modifications, e.g. when emulating and/or intercepting instructions in
userspace.
For s390 specifics, please refer to the source code.
For x86:
- the register sets to be copied out to kvm_run are selectable
by userspace (rather that all sets being copied out for every exit).
- vcpu_events are available in addition to regs and sregs.
For x86, the 'kvm_valid_regs' field of struct kvm_run is overloaded to
function as an input bit-array field set by userspace to indicate the
specific register sets to be copied out on the next exit.
To indicate when userspace has modified values that should be copied into
the vCPU, the all architecture bitarray field, 'kvm_dirty_regs' must be set.
This is done using the same bitflags as for the 'kvm_valid_regs' field.
If the dirty bit is not set, then the register set values will not be copied
into the vCPU even if they've been modified.
Unused bitfields in the bitarrays must be set to zero.
::
struct kvm_sync_regs {
struct kvm_regs regs;
struct kvm_sregs sregs;
struct kvm_vcpu_events events;
};
6.75 KVM_CAP_PPC_IRQ_XIVE
-------------------------
:Architectures: ppc
:Target: vcpu
:Parameters: args[0] is the XIVE device fd;
args[1] is the XIVE CPU number (server ID) for this vcpu
This capability connects the vcpu to an in-kernel XIVE device.
6.76 KVM_CAP_HYPERV_SYNIC
-------------------------
:Architectures: x86
:Target: vcpu
This capability, if KVM_CHECK_EXTENSION indicates that it is
available, means that the kernel has an implementation of the
Hyper-V Synthetic interrupt controller(SynIC). Hyper-V SynIC is
used to support Windows Hyper-V based guest paravirt drivers(VMBus).
In order to use SynIC, it has to be activated by setting this
capability via KVM_ENABLE_CAP ioctl on the vcpu fd. Note that this
will disable the use of APIC hardware virtualization even if supported
by the CPU, as it's incompatible with SynIC auto-EOI behavior.
6.77 KVM_CAP_HYPERV_SYNIC2
--------------------------
:Architectures: x86
:Target: vcpu
This capability enables a newer version of Hyper-V Synthetic interrupt
controller (SynIC). The only difference with KVM_CAP_HYPERV_SYNIC is that KVM
doesn't clear SynIC message and event flags pages when they are enabled by
writing to the respective MSRs.
6.78 KVM_CAP_HYPERV_DIRECT_TLBFLUSH
-----------------------------------
:Architectures: x86
:Target: vcpu
This capability indicates that KVM running on top of Hyper-V hypervisor
enables Direct TLB flush for its guests meaning that TLB flush
hypercalls are handled by Level 0 hypervisor (Hyper-V) bypassing KVM.
Due to the different ABI for hypercall parameters between Hyper-V and
KVM, enabling this capability effectively disables all hypercall
handling by KVM (as some KVM hypercall may be mistakenly treated as TLB
flush hypercalls by Hyper-V) so userspace should disable KVM identification
in CPUID and only exposes Hyper-V identification. In this case, guest
thinks it's running on Hyper-V and only use Hyper-V hypercalls.
6.79 KVM_CAP_HYPERV_ENFORCE_CPUID
---------------------------------
:Architectures: x86
:Target: vcpu
When enabled, KVM will disable emulated Hyper-V features provided to the
guest according to the bits Hyper-V CPUID feature leaves. Otherwise, all
currently implemented Hyper-V features are provided unconditionally when
Hyper-V identification is set in the HYPERV_CPUID_INTERFACE (0x40000001)
leaf.
6.80 KVM_CAP_ENFORCE_PV_FEATURE_CPUID
-------------------------------------
:Architectures: x86
:Target: vcpu
When enabled, KVM will disable paravirtual features provided to the
guest according to the bits in the KVM_CPUID_FEATURES CPUID leaf
(0x40000001). Otherwise, a guest may use the paravirtual features
regardless of what has actually been exposed through the CPUID leaf.
.. _KVM_CAP_DIRTY_LOG_RING:
.. _cap_enable_vm:
7. VM capabilities: 7.1-7.12
7656-7904VM capability도 `KVM_ENABLE_CAP`으로 활성화하며 VM 전체 실행 계약을 바꿉니다. 이 범위는 PowerPC hcall·SMT·FWNMI, s390 SIGP·vector·STSI·runtime facility, x86 split irqchip·x2APIC을 다룹니다.
`KVM_CAP_PPC_ENABLE_HCALL`은 `args[0]`의 sPAPR hcall을 kernel에서 처리할지 `args[1]`로 정합니다. 비활성화하면 항상 userspace로 exit하며 kernel 구현이 없는 hcall 번호는 `EINVAL`입니다.
관련 hcall 일부만 enable하거나 disable하는 조합이 무의미할 수 있지만 KVM은 막지 않습니다. VM 생성 시 capability 도입 전부터 kernel handler가 있던 초기 hcall 집합은 기본 enable됩니다.
Capability효과·제약
`KVM_CAP_S390_USER_SIGP`Fast SIGP order는 kernel, 나머지는 완전 userspace 처리
`KVM_CAP_S390_VECTOR_REGISTERS`z13 vector register 사용·동기화; 미지원 machine은 `EINVAL`
`KVM_CAP_S390_USER_STSI`kernel 선처리 뒤 `KVM_EXIT_S390_STSI` post-handler를 userspace에 허용
`KVM_CAP_S390_RI`zEC12 runtime instrumentation; 미지원은 `EINVAL`, vCPU 생성 뒤에는 `EBUSY`
`KVM_CAP_S390_USER_INSTR0`illegal 2-byte `0x0000` instruction을 userspace software breakpoint용으로 전달
`KVM_CAP_S390_GS`guarded storage 허용; 미지원 `EINVAL`, vCPU 생성 뒤 `EBUSY`
`KVM_CAP_S390_AIS`adapter-interruption suppression 허용; vCPU 생성 뒤 `EBUSY`
Userspace interception과 processor facility를 선택합니다.
USER_SIGP에서는 SENSE, SENSE RUNNING, EXTERNAL CALL, EMERGENCY SIGNAL, CONDITIONAL EMERGENCY SIGNAL이 fast order로 kernel에서 처리되고 그 밖의 order는 userspace가 전부 처리합니다. Kernel·hardware는 privileged-operation exception만 확인합니다.
USER_STSI exit 전에 kernel은 `s390_stsi`에 SYSIB guest address, access-register 번호, function code와 selector를 채우고 `-EREMOTE`로 userspace에 나옵니다.
`KVM_CAP_SPLIT_IRQCHIP`은 processor마다 local APIC만 kernel에 만들고 userspace VMM이 IOAPIC·PIC와 별도 enable한 PIT를 emulate하게 합니다. `args[0]`은 userspace IOAPIC용으로 예약할 route 수입니다.
Split mode에서는 IRQ routing table에 MSI route만 쓰고 처음 `args[0]`개를 IOAPIC pin에 예약합니다. 해당 route에 LAPIC EOI가 오면 `KVM_EXIT_IOAPIC_EOI`를 보고합니다. vCPU가 이미 있거나 `KVM_CREATE_IRQCHIP`을 호출한 뒤에는 실패합니다.
Flag효과
`KVM_X2APIC_API_USE_32BIT_IDS`GSI routing, MSI signal, LAPIC get/set에서 32비트 APIC ID 허용
`KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK`x2APIC logical mode 또는 255개 초과 vCPU에서 `0xff` broadcast quirk 제거
`KVM_X2APIC_ENABLE_SUPPRESS_EOI_BROADCAST`Split irqchip에서 guest에 기능을 광고하고 SPIV bit에 따라 broadcast 억제
`KVM_X2APIC_DISABLE_SUPPRESS_EOI_BROADCAST`Suppress EOI Broadcast 지원과 광고를 완전히 비활성화
32비트 APIC ID와 EOI broadcast 동작을 정합니다.
Modern VMM은 suppress EOI broadcast enable 또는 disable flag 중 하나를 명시해야 합니다. 둘 다 없으면 split mode에서 지원을 광고하면서 실제로 억제하지 않는 legacy 동작을 사용합니다.
Enable과 disable flag를 함께 지정하거나 split irqchip 없이 enable flag를 쓰면 `EINVAL`입니다.
`KVM_CAP_S390_USER_INSTR0`은 실행 중인 vCPU가 있어도 동적으로 enable할 수 있습니다. Kernel은 operation exception을 주입하지 않으므로 userspace가 필요한 예외 처리를 담당합니다.
`KVM_CAP_PPC_SMT`는 HV KVM에서 vCPU 생성 전에 virtual core당 vCPU 수 `vsmt_mode`를 설정합니다. 1~8 사이 2의 거듭제곱이어야 하고 POWER8에서는 host subcore thread 수를 넘을 수 없으며 flags는 0입니다.
성공 뒤 VM의 `KVM_CAP_PPC_SMT` 조회는 설정한 mode를 반환하고 `KVM_CAP_PPC_SMT_POSSIBLE`은 가능한 virtual SMT mode를 나타냅니다.
`KVM_CAP_PPC_FWNMI`는 guest address-space machine check 때 0x200 vector로 바로 branch하는 대신 NMI exit를 발생시켜 QEMU가 error log를 만들고 guest가 등록한 machine-check handler로 넘기게 합니다.
7. Capabilities that can be enabled on VMs
==========================================
There are certain capabilities that change the behavior of the virtual
machine when enabled. To enable them, please see section
:ref:`KVM_ENABLE_CAP`. Below you can find a list of capabilities and
what their effect on the VM is when enabling them.
The following information is provided along with the description:
Architectures:
which instruction set architectures provide this ioctl.
x86 includes both i386 and x86_64.
Parameters:
what parameters are accepted by the capability.
Returns:
the return value. General error numbers (EBADF, ENOMEM, EINVAL)
are not detailed, but errors with specific meanings are.
7.1 KVM_CAP_PPC_ENABLE_HCALL
----------------------------
:Architectures: ppc
:Parameters: args[0] is the sPAPR hcall number;
args[1] is 0 to disable, 1 to enable in-kernel handling
This capability controls whether individual sPAPR hypercalls (hcalls)
get handled by the kernel or not. Enabling or disabling in-kernel
handling of an hcall is effective across the VM. On creation, an
initial set of hcalls are enabled for in-kernel handling, which
consists of those hcalls for which in-kernel handlers were implemented
before this capability was implemented. If disabled, the kernel will
not to attempt to handle the hcall, but will always exit to userspace
to handle it. Note that it may not make sense to enable some and
disable others of a group of related hcalls, but KVM does not prevent
userspace from doing that.
If the hcall number specified is not one that has an in-kernel
implementation, the KVM_ENABLE_CAP ioctl will fail with an EINVAL
error.
7.2 KVM_CAP_S390_USER_SIGP
--------------------------
:Architectures: s390
:Parameters: none
This capability controls which SIGP orders will be handled completely in user
space. With this capability enabled, all fast orders will be handled completely
in the kernel:
- SENSE
- SENSE RUNNING
- EXTERNAL CALL
- EMERGENCY SIGNAL
- CONDITIONAL EMERGENCY SIGNAL
All other orders will be handled completely in user space.
Only privileged operation exceptions will be checked for in the kernel (or even
in the hardware prior to interception). If this capability is not enabled, the
old way of handling SIGP orders is used (partially in kernel and user space).
7.3 KVM_CAP_S390_VECTOR_REGISTERS
---------------------------------
:Architectures: s390
:Parameters: none
:Returns: 0 on success, negative value on error
Allows use of the vector registers introduced with z13 processor, and
provides for the synchronization between host and user space. Will
return -EINVAL if the machine does not support vectors.
7.4 KVM_CAP_S390_USER_STSI
--------------------------
:Architectures: s390
:Parameters: none
This capability allows post-handlers for the STSI instruction. After
initial handling in the kernel, KVM exits to user space with
KVM_EXIT_S390_STSI to allow user space to insert further data.
Before exiting to userspace, kvm handlers should fill in s390_stsi field of
vcpu->run::
struct {
__u64 addr;
__u8 ar;
__u8 reserved;
__u8 fc;
__u8 sel1;
__u16 sel2;
} s390_stsi;
@addr - guest address of STSI SYSIB
@fc - function code
@sel1 - selector 1
@sel2 - selector 2
@ar - access register number
KVM handlers should exit to userspace with rc = -EREMOTE.
7.5 KVM_CAP_SPLIT_IRQCHIP
-------------------------
:Architectures: x86
:Parameters: args[0] - number of routes reserved for userspace IOAPICs
:Returns: 0 on success, -1 on error
Create a local apic for each processor in the kernel. This can be used
instead of KVM_CREATE_IRQCHIP if the userspace VMM wishes to emulate the
IOAPIC and PIC (and also the PIT, even though this has to be enabled
separately).
This capability also enables in kernel routing of interrupt requests;
when KVM_CAP_SPLIT_IRQCHIP only routes of KVM_IRQ_ROUTING_MSI type are
used in the IRQ routing table. The first args[0] MSI routes are reserved
for the IOAPIC pins. Whenever the LAPIC receives an EOI for these routes,
a KVM_EXIT_IOAPIC_EOI vmexit will be reported to userspace.
Fails if VCPU has already been created, or if the irqchip is already in the
kernel (i.e. KVM_CREATE_IRQCHIP has already been called).
7.6 KVM_CAP_S390_RI
-------------------
:Architectures: s390
:Parameters: none
Allows use of runtime-instrumentation introduced with zEC12 processor.
Will return -EINVAL if the machine does not support runtime-instrumentation.
Will return -EBUSY if a VCPU has already been created.
7.7 KVM_CAP_X2APIC_API
----------------------
:Architectures: x86
:Parameters: args[0] - features that should be enabled
:Returns: 0 on success, -EINVAL when args[0] contains invalid features
Valid feature flags in args[0] are::
#define KVM_X2APIC_API_USE_32BIT_IDS (1ULL << 0)
#define KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK (1ULL << 1)
#define KVM_X2APIC_ENABLE_SUPPRESS_EOI_BROADCAST (1ULL << 2)
#define KVM_X2APIC_DISABLE_SUPPRESS_EOI_BROADCAST (1ULL << 3)
Enabling KVM_X2APIC_API_USE_32BIT_IDS changes the behavior of
KVM_SET_GSI_ROUTING, KVM_SIGNAL_MSI, KVM_SET_LAPIC, and KVM_GET_LAPIC,
allowing the use of 32-bit APIC IDs. See KVM_CAP_X2APIC_API in their
respective sections.
KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK must be enabled for x2APIC to work
in logical mode or with more than 255 VCPUs. Otherwise, KVM treats 0xff
as a broadcast even in x2APIC mode in order to support physical x2APIC
without interrupt remapping. This is undesirable in logical mode,
where 0xff represents CPUs 0-7 in cluster 0.
Setting KVM_X2APIC_ENABLE_SUPPRESS_EOI_BROADCAST instructs KVM to enable
Suppress EOI Broadcasts. KVM will advertise support for Suppress EOI
Broadcast to the guest and suppress LAPIC EOI broadcasts when the guest
sets the Suppress EOI Broadcast bit in the SPIV register. This flag is
supported only when using a split IRQCHIP.
Setting KVM_X2APIC_DISABLE_SUPPRESS_EOI_BROADCAST disables support for
Suppress EOI Broadcasts entirely, i.e. instructs KVM to NOT advertise
support to the guest.
Modern VMMs should either enable KVM_X2APIC_ENABLE_SUPPRESS_EOI_BROADCAST
or KVM_X2APIC_DISABLE_SUPPRESS_EOI_BROADCAST. If not, legacy quirky
behavior will be used by KVM: in split IRQCHIP mode, KVM will advertise
support for Suppress EOI Broadcasts but not actually suppress EOI
broadcasts; for in-kernel IRQCHIP mode, KVM will not advertise support for
Suppress EOI Broadcasts.
Setting both KVM_X2APIC_ENABLE_SUPPRESS_EOI_BROADCAST and
KVM_X2APIC_DISABLE_SUPPRESS_EOI_BROADCAST will fail with an EINVAL error,
as will setting KVM_X2APIC_ENABLE_SUPPRESS_EOI_BROADCAST without a split
IRCHIP.
7.8 KVM_CAP_S390_USER_INSTR0
----------------------------
:Architectures: s390
:Parameters: none
With this capability enabled, all illegal instructions 0x0000 (2 bytes) will
be intercepted and forwarded to user space. User space can use this
mechanism e.g. to realize 2-byte software breakpoints. The kernel will
not inject an operating exception for these instructions, user space has
to take care of that.
This capability can be enabled dynamically even if VCPUs were already
created and are running.
7.9 KVM_CAP_S390_GS
-------------------
:Architectures: s390
:Parameters: none
:Returns: 0 on success; -EINVAL if the machine does not support
guarded storage; -EBUSY if a VCPU has already been created.
Allows use of guarded storage for the KVM guest.
7.10 KVM_CAP_S390_AIS
---------------------
:Architectures: s390
:Parameters: none
Allow use of adapter-interruption suppression.
:Returns: 0 on success; -EBUSY if a VCPU has already been created.
7.11 KVM_CAP_PPC_SMT
--------------------
:Architectures: ppc
:Parameters: vsmt_mode, flags
Enabling this capability on a VM provides userspace with a way to set
the desired virtual SMT mode (i.e. the number of virtual CPUs per
virtual core). The virtual SMT mode, vsmt_mode, must be a power of 2
between 1 and 8. On POWER8, vsmt_mode must also be no greater than
the number of threads per subcore for the host. Currently flags must
be 0. A successful call to enable this capability will result in
vsmt_mode being returned when the KVM_CAP_PPC_SMT capability is
subsequently queried for the VM. This capability is only supported by
HV KVM, and can only be set before any VCPUs have been created.
The KVM_CAP_PPC_SMT_POSSIBLE capability indicates which virtual SMT
modes are available.
7.12 KVM_CAP_PPC_FWNMI
----------------------
:Architectures: ppc
:Parameters: none
With this capability a machine check exception in the guest address
space will cause KVM to exit the guest with NMI exit reason. This
enables QEMU to build error log and branch to guest kernel registered
machine check handling routine. Without this capability KVM will
branch to guests' 0x200 interrupt vector.
7. VM capabilities: 7.13-7.43
7905-8726`KVM_CAP_X86_DISABLE_EXITS`는 전용 physical CPU에 vCPU를 고정한 workload 등의 latency를 줄이기 위해 MWAIT, HLT, PAUSE, C-state와 APERF/MPERF interception을 선택적으로 끕니다. vCPU 생성 뒤 또는 유효하지 않은 bit에는 `EINVAL`입니다.
Bit비활성화할 exit
`KVM_X86_DISABLE_EXITS_MWAIT`MONITOR/MWAIT
`KVM_X86_DISABLE_EXITS_HLT`HLT
`KVM_X86_DISABLE_EXITS_PAUSE`PAUSE
`KVM_X86_DISABLE_EXITS_CSTATE`C-state
`KVM_X86_DISABLE_EXITS_APERFMPERF`IA32_APERF·IA32_MPERF
향후 bit가 추가될 수 있어 userspace는 `KVM_CHECK_EXTENSION` 결과 전체를 전달할 수 있습니다.
HLT exit를 끄면 `KVM_FEATURE_PV_UNHALT`를 enable하면 안 됩니다. APERF/MPERF passthrough만으로는 vCPU migration, live migration·suspend, CPU 공유, C-state emulation, guest·host TSC 불일치 때 delta 비율이 틀릴 수 있습니다.
따라서 KVM은 guest `CPUID.6:ECX.APERFMPERF[0]`를 자동 설정하지 않습니다. 이 방식이 충분하다고 판단한 VMM이 CPUID bit를 명시적으로 설정해야 합니다.
Capability효과
`KVM_CAP_S390_HPAGE_1M`hugetlbfs 1MiB backing 허용; CMMA·UCONTROL·module parameter와 상호 제약
`KVM_CAP_MSR_PLATFORM_INFO`x86 guest의 `MSR_PLATFORM_INFO` read 허용; write는 허용하지 않음
`KVM_CAP_PPC_NESTED_HV`POWER9+ HV-KVM guest가 supervisor mode L2 guest 실행
`KVM_CAP_EXCEPTION_PAYLOAD`Nested #PF/#DB payload와 pending·injected 상태를 userspace에 보존
`KVM_CAP_PPC_SECURE_GUEST`Ultravisor secure mode 전환을 KVM이 허용
`KVM_CAP_HALT_POLL`VM 모든 vCPU의 최대 halt-poll nanosecond를 동적으로 설정
Memory backing, nested exception과 halt polling을 구성합니다.
s390 1MiB page capability가 enable되면 CMMA를 더는 enable할 수 없고 PFMFI와 storage-key interpretation이 꺼집니다. Capability 없이 hugepage-backed VM을 만들 수는 있어도 실행할 수 없습니다.
Nested exception payload를 enable하면 L1이 L2의 #PF를 intercept하기 전 CR2를, kvm-intel의 #DB에서는 DR6를 수정하지 않습니다. GET/SET_VCPU_EVENTS의 `has_payload`와 `exception_payload`로 fault address 또는 새 DR6 bit를 교환합니다.
새 DR6 bit 16은 #DB가 DR6.RTM을 clear할 때만 set됩니다. Capability는 `exception.pending`도 enable해 pending exception과 이미 injected된 exception을 구분하게 합니다.
`KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2`의 `KVM_DIRTY_LOG_MANUAL_PROTECT_ENABLE`은 `KVM_GET_DIRTY_LOG`가 dirty page를 자동 clear·write-protect하지 않게 하고 userspace가 `KVM_CLEAR_DIRTY_LOG`로 64-page 단위 reprotection을 수행하게 합니다.
작은 범위만 lock하고 dirty bitmap 사용 직전까지 reprotection을 미뤄 guest write fault와 false-positive dirty report를 줄이므로 확장성과 응답성이 좋아집니다.
`KVM_DIRTY_LOG_INITIALLY_SET`은 bitmap을 모두 1로 시작해 첫 `KVM_CLEAR_DIRTY_LOG`부터 작은 묶음씩 logging을 활성화합니다. Manual protect에 의존하며 현재 x86·arm64에서만 사용할 수 있습니다.
과거 `KVM_CAP_MANUAL_DIRTY_LOG_PROTECT` 구현에는 올바른 사용을 어렵게 하는 bug가 있으므로 userspace는 사용하지 말고 `PROTECT2`만 확인해야 합니다.
PowerPC secure guest에서는 host가 명시적으로 공유된 page 외의 memory를 읽지 못합니다. Ultravisor가 전환 요청을 KVM에 알리고 capability가 enable된 VM만 KVM이 이를 승인합니다.
`KVM_CAP_X86_USER_SPACE_MSR`은 기본 `#GP` 대상인 거부 MSR access를 reason mask에 따라 `KVM_EXIT_X86_RDMSR`·`WRMSR`로 보냅니다. UNKNOWN, architecture-invalid, userspace filter 거부를 각각 선택할 수 있습니다.
`KVM_CAP_X86_BUS_LOCK_EXIT`은 guest bus lock 정책을 상호 배타적인 OFF 또는 EXIT로 정합니다. Host split-lock #AC 설정과 무관하게 malicious guest의 system-wide 성능 저하를 완화할 수 있습니다.
EXIT mode에서는 `KVM_RUN_X86_BUS_LOCK`을 항상 확인해야 합니다. 다른 primary exit와 동시에 검출될 수 있어 `exit_reason`이 반드시 `KVM_EXIT_X86_BUS_LOCK`인 것은 아닙니다.
Intel에서는 exit 시 RIP가 다음 instruction을 가리키는 trap 방식이고 AMD에서는 offending instruction을 가리키는 fault 방식입니다.
Capability효과
`KVM_CAP_PPC_DAWR1`POWER10 두 번째 DAWR 지원 확인·enable
`KVM_CAP_VM_COPY_ENC_CONTEXT_FROM`Source x86 SEV VM의 encryption context를 복사해 별도 APIC·MSR 환경의 in-guest workload 지원
`KVM_CAP_SGX_ATTRIBUTE`securityfs SGX attribute fd로 VM에 PROVISIONKEY 같은 privileged enclave attribute 부여
`KVM_CAP_VM_MOVE_ENC_CONTEXT_FROM`Source SEV VM context를 이동해 guest 중단 없는 host 내부 VMM migration 지원
Privileged attribute와 encryption context의 소유·이동을 제어합니다.
SGX는 malware의 안정적 system fingerprint 획득을 막기 위해 PROVISIONKEY 같은 attribute를 제한합니다. VM으로 제한을 우회하지 못하도록 KVM은 기본 거부하며 유효하고 지원되는 attribute file fd만 허용합니다.
`KVM_CAP_EXIT_ON_EMULATION_FAILURE`은 VMware backdoor instruction을 제외한 x86 emulation failure를 `KVM_INTERNAL_ERROR`로 userspace에 보냅니다. 유효 flag가 있으면 최대 15바이트 instruction과 길이를 `emulation_failure` 구조에서 제공합니다.
`KVM_CAP_ARM_MTE`는 AArch64 guest에 Memory Tagging Extension을 노출하며 vCPU 생성 전에 enable해야 합니다. Enable 후 AArch32 vCPU 생성은 실패합니다.
KVM은 host swap·hibernation 중 tag를 보존하지만 VM migration 때는 VMM이 `KVM_ARM_MTE_COPY_TAGS`로 tag를 저장·복원해야 합니다. 모든 memslot은 anonymous 또는 tmpfs·memfd RAM mapping이어야 하며 그 밖의 mmap은 `EINVAL`입니다.
`KVM_CAP_DISABLE_QUIRKS2` 조회는 비활성화 가능한 x86 quirk bitmask를 반환하고 enable argument는 그 부분집합이어야 합니다.
Quirk비활성화 결과
`KVM_X86_QUIRK_LINT0_REENABLED`LVT LINT0 reset을 ExtINT 0x700 대신 masked 0x10000으로
`KVM_X86_QUIRK_CD_NW_CLEARED`AMD에서 CR0.CD·NW를 강제 clear하지 않음
`KVM_X86_QUIRK_LAPIC_MMIO_HOLE`x2APIC mode에서 MMIO LAPIC interface 비활성화
`KVM_X86_QUIRK_OUT_7E_INC_RIP`port 0x7e OUT userspace exit 전에 RIP를 미리 증가시키지 않음
`KVM_X86_QUIRK_MISC_ENABLE_NO_MWAIT`MISC_ENABLE.MWAIT와 guest CPUID MONITOR/MWAIT bit를 일치시킴
`KVM_X86_QUIRK_FIX_HYPERCALL_INSN`잘못된 vendor VMCALL/VMMCALL을 rewrite하지 않고 guest `#UD`
`KVM_X86_QUIRK_MWAIT_NEVER_UD_FAULTS`CPUID 미지원 MONITOR/MWAIT interception에 `#UD` 주입
`KVM_X86_QUIRK_SLOT_ZAP_ALL`memslot 이동·삭제 때 관련 SPTE만 선택적으로 무효화 가능
`KVM_X86_QUIRK_STUFF_FEATURE_MSRS`feature MSR 자동 최대값 대신 대부분 0으로 시작해 userspace가 CPU model 통제
`KVM_X86_QUIRK_IGNORE_GUEST_PAT`안전한 Intel 구성에서 guest PAT를 존중
`KVM_X86_QUIRK_VMCS12_ALLOW_FREEZE_IN_SMM`vmcs12 GUEST_IA32_DEBUGCTL FREEZE_IN_SMM relaxed check 제거
Bit를 선택하면 해당 legacy 기본 동작을 끕니다.
Feature-MSR quirk를 끄더라도 safety 때문에 userspace가 설정할 수 없는 VMX CR0_FIXED1·CR4_FIXED1은 guest CPUID를 기반으로 KVM이 유지합니다. Guest PAT quirk는 self-snoop이 없거나 non-coherent DMA device가 연결된 등 안전하지 않은 환경에서는 사용할 수 없습니다.
`KVM_CAP_MAX_VCPU_ID`는 vCPU 생성 전에 topology에서 계산한 최대 APIC ID를 설정해 APIC-ID-indexed 구조의 memory를 줄입니다. 한 번 nonzero로 설정하거나 vCPU를 만들면 변경할 수 없고, 미설정이면 capability 조회값을 사용합니다.
`KVM_CAP_X86_NOTIFY_VMEXIT`은 `args[0]` 상위 32비트 notify window와 하위 flag로 non-root mode event window가 장시간 열리지 않는 악성 VM을 감시합니다. ENABLED가 기능을 켜고 USER가 userspace exit를 요청합니다.
`KVM_CAP_X86_APIC_BUS_CYCLES_NS`는 in-kernel APIC timer의 bus-clock nanosecond 값을 vCPU 생성 전에 설정합니다. Virtual LAPIC이 없으면 `ENXIO`; guest CPUID leaf 0x15를 노출하면 userspace가 core crystal frequency를 일치시켜야 합니다.
`KVM_CAP_DIRTY_LOG_RING`과 `_ACQ_REL`은 vCPU마다 userspace에 mmap되는 `kvm_dirty_gfn` ring으로 slot과 GFN offset의 dirty 상태를 전달합니다. VM 생성 직후 vCPU 생성 전에 2의 거듭제곱 크기로 enable하며 최소 64KiB, 4096 entry를 권장합니다.
상태의미
`00`미사용 entry
`01`KVM이 기록한 dirty GFN
`1X`userspace가 수확했고 reset을 기다림
`flags`의 두 bit로 producer·consumer 상태를 표현합니다.
00 unused→KVM dirtied → 01→userspace harvested → 1X→KVM reset → 00
Userspace는 entry를 건너뛰지 않고 순서대로 수확합니다.
Userspace는 DIRTY bit가 clear될 때까지 연속 entry를 읽고 RESET bit를 set해 harvested로 표시합니다. Weakly ordered architecture에서는 load-acquire·store-release 또는 동등한 barrier가 필요합니다.
Entry 처리 뒤 `KVM_RESET_DIRTY_RINGS`를 호출해 KVM이 해당 GFN을 reprotect하게 해야 하며 dirty page 내용을 읽기 전에 호출해야 합니다. Ring이 가득 차면 vCPU는 `KVM_EXIT_DIRTY_LOG_FULL`로 나옵니다.
Processor dirty-page buffer를 ring으로 flush하려면 signal로 vCPU를 `KVM_RUN`에서 kick해 vmexit를 만들어야 합니다. Weakly ordered architecture는 추가 ordering 계약을 나타내는 `_ACQ_REL`만 노출해야 하고 x86 같은 TSO는 둘 다 노출할 수 있습니다.
`KVM_CAP_DIRTY_LOG_RING_WITH_BITMAP`은 vCPU·ring context 밖에서 생긴 dirty 정보를 per-slot backup bitmap에 보존합니다. `_ACQ_REL` 없이 또는 memslot 생성 뒤에는 enable할 수 없습니다.
Backup bitmap은 out-of-context dirty가 적을 때만 유리합니다. `KVM_GET_DIRTY_LOG`로 마지막에 한 번 수집하고 이후 ioctl이 새 dirty page를 만들지 않도록 최종 상태를 보장해야 합니다. 단일 pass라면 `KVM_CLEAR_DIRTY_LOG`는 필요 없습니다.
Capability효과
`KVM_CAP_PMU_CAPABILITY`현재 `KVM_PMU_CAP_DISABLE`로 VM PMU virtualization 비활성화; CPUID 0xA도 조정
`KVM_CAP_VM_DISABLE_NX_HUGE_PAGES`iTLB MULTIHIT NX huge-page mitigation 비활성화; `CAP_SYS_BOOT` 필요
`KVM_CAP_ARM_EAGER_SPLIT_CHUNK_SIZE`dirty logging 전에 huge page를 지정 block-size chunk로 선분할
vCPU 생성이나 memslot 생성 전 설정 제약이 있습니다.
Eager splitting은 fault 시점의 huge-page 분할을 dirty logging enable 또는 `KVM_CLEAR_DIRTY_LOG` 시점으로 당깁니다. 큰 chunk는 더 많은 page를 미리 할당하며 지원 block size는 `KVM_CAP_ARM_SUPPORTED_BLOCK_SIZES` bitmap에서 얻고 0은 기능 비활성화입니다.
`KVM_CAP_EXIT_HYPERCALL`은 선택한 x86 hypercall을 `KVM_EXIT_HYPERCALL`로 전달합니다. 현재 configurable call은 `KVM_HC_MAP_GPA_RANGE`이며 enable mask 밖 call은 `ENOSYS`를 반환합니다.
`KVM_CAP_ARM_SYSTEM_SUSPEND`은 guest suspend 요청을 `KVM_SYSTEM_EVENT_SUSPEND` exit로 보냅니다.
`KVM_CAP_ARM_WRITABLE_IMP_ID_REGS`는 vCPU 생성 전에 enable해 `MIDR_EL1`, `REVIDR_EL1`, `AIDR_EL1`을 첫 `KVM_RUN` 전 userspace가 바꾸게 합니다. 값은 VM 범위라 모든 vCPU에 동일합니다.
`KVM_CAP_RISCV_MP_STATE_RESET`은 ioctl로 `MP_STATE_INIT_RECEIVED`를 설정할 때 vCPU를 reset하되 원래 MP state는 보존합니다. `args[0]`은 0이어야 합니다.
7.13 KVM_CAP_X86_DISABLE_EXITS
------------------------------
:Architectures: x86
:Parameters: args[0] defines which exits are disabled
:Returns: 0 on success, -EINVAL when args[0] contains invalid exits
or if any vCPUs have already been created
Valid bits in args[0] are::
#define KVM_X86_DISABLE_EXITS_MWAIT (1 << 0)
#define KVM_X86_DISABLE_EXITS_HLT (1 << 1)
#define KVM_X86_DISABLE_EXITS_PAUSE (1 << 2)
#define KVM_X86_DISABLE_EXITS_CSTATE (1 << 3)
#define KVM_X86_DISABLE_EXITS_APERFMPERF (1 << 4)
Enabling this capability on a VM provides userspace with a way to no
longer intercept some instructions for improved latency in some
workloads, and is suggested when vCPUs are associated to dedicated
physical CPUs. More bits can be added in the future; userspace can
just pass the KVM_CHECK_EXTENSION result to KVM_ENABLE_CAP to disable
all such vmexits.
Do not enable KVM_FEATURE_PV_UNHALT if you disable HLT exits.
Virtualizing the ``IA32_APERF`` and ``IA32_MPERF`` MSRs requires more
than just disabling APERF/MPERF exits. While both Intel and AMD
document strict usage conditions for these MSRs--emphasizing that only
the ratio of their deltas over a time interval (T0 to T1) is
architecturally defined--simply passing through the MSRs can still
produce an incorrect ratio.
This erroneous ratio can occur if, between T0 and T1:
1. The vCPU thread migrates between logical processors.
2. Live migration or suspend/resume operations take place.
3. Another task shares the vCPU's logical processor.
4. C-states lower than C0 are emulated (e.g., via HLT interception).
5. The guest TSC frequency doesn't match the host TSC frequency.
Due to these complexities, KVM does not automatically associate this
passthrough capability with the guest CPUID bit,
``CPUID.6:ECX.APERFMPERF[bit 0]``. Userspace VMMs that deem this
mechanism adequate for virtualizing the ``IA32_APERF`` and
``IA32_MPERF`` MSRs must set the guest CPUID bit explicitly.
7.14 KVM_CAP_S390_HPAGE_1M
--------------------------
:Architectures: s390
:Parameters: none
:Returns: 0 on success, -EINVAL if hpage module parameter was not set
or cmma is enabled, or the VM has the KVM_VM_S390_UCONTROL
flag set
With this capability the KVM support for memory backing with 1m pages
through hugetlbfs can be enabled for a VM. After the capability is
enabled, cmma can't be enabled anymore and pfmfi and the storage key
interpretation are disabled. If cmma has already been enabled or the
hpage module parameter is not set to 1, -EINVAL is returned.
While it is generally possible to create a huge page backed VM without
this capability, the VM will not be able to run.
7.15 KVM_CAP_MSR_PLATFORM_INFO
------------------------------
:Architectures: x86
:Parameters: args[0] whether feature should be enabled or not
With this capability, a guest may read the MSR_PLATFORM_INFO MSR. Otherwise,
a #GP would be raised when the guest tries to access. Currently, this
capability does not enable write permissions of this MSR for the guest.
7.16 KVM_CAP_PPC_NESTED_HV
--------------------------
:Architectures: ppc
:Parameters: none
:Returns: 0 on success, -EINVAL when the implementation doesn't support
nested-HV virtualization.
HV-KVM on POWER9 and later systems allows for "nested-HV"
virtualization, which provides a way for a guest VM to run guests that
can run using the CPU's supervisor mode (privileged non-hypervisor
state). Enabling this capability on a VM depends on the CPU having
the necessary functionality and on the facility being enabled with a
kvm-hv module parameter.
7.17 KVM_CAP_EXCEPTION_PAYLOAD
------------------------------
:Architectures: x86
:Parameters: args[0] whether feature should be enabled or not
With this capability enabled, CR2 will not be modified prior to the
emulated VM-exit when L1 intercepts a #PF exception that occurs in
L2. Similarly, for kvm-intel only, DR6 will not be modified prior to
the emulated VM-exit when L1 intercepts a #DB exception that occurs in
L2. As a result, when KVM_GET_VCPU_EVENTS reports a pending #PF (or
#DB) exception for L2, exception.has_payload will be set and the
faulting address (or the new DR6 bits*) will be reported in the
exception_payload field. Similarly, when userspace injects a #PF (or
#DB) into L2 using KVM_SET_VCPU_EVENTS, it is expected to set
exception.has_payload and to put the faulting address - or the new DR6
bits\ [#]_ - in the exception_payload field.
This capability also enables exception.pending in struct
kvm_vcpu_events, which allows userspace to distinguish between pending
and injected exceptions.
.. [#] For the new DR6 bits, note that bit 16 is set iff the #DB exception
will clear DR6.RTM.
7.18 KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2
--------------------------------------
:Architectures: x86, arm64, mips
:Parameters: args[0] whether feature should be enabled or not
Valid flags are::
#define KVM_DIRTY_LOG_MANUAL_PROTECT_ENABLE (1 << 0)
#define KVM_DIRTY_LOG_INITIALLY_SET (1 << 1)
With KVM_DIRTY_LOG_MANUAL_PROTECT_ENABLE is set, KVM_GET_DIRTY_LOG will not
automatically clear and write-protect all pages that are returned as dirty.
Rather, userspace will have to do this operation separately using
KVM_CLEAR_DIRTY_LOG.
At the cost of a slightly more complicated operation, this provides better
scalability and responsiveness for two reasons. First,
KVM_CLEAR_DIRTY_LOG ioctl can operate on a 64-page granularity rather
than requiring to sync a full memslot; this ensures that KVM does not
take spinlocks for an extended period of time. Second, in some cases a
large amount of time can pass between a call to KVM_GET_DIRTY_LOG and
userspace actually using the data in the page. Pages can be modified
during this time, which is inefficient for both the guest and userspace:
the guest will incur a higher penalty due to write protection faults,
while userspace can see false reports of dirty pages. Manual reprotection
helps reducing this time, improving guest performance and reducing the
number of dirty log false positives.
With KVM_DIRTY_LOG_INITIALLY_SET set, all the bits of the dirty bitmap
will be initialized to 1 when created. This also improves performance because
dirty logging can be enabled gradually in small chunks on the first call
to KVM_CLEAR_DIRTY_LOG. KVM_DIRTY_LOG_INITIALLY_SET depends on
KVM_DIRTY_LOG_MANUAL_PROTECT_ENABLE (it is also only available on
x86 and arm64 for now).
KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 was previously available under the name
KVM_CAP_MANUAL_DIRTY_LOG_PROTECT, but the implementation had bugs that make
it hard or impossible to use it correctly. The availability of
KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 signals that those bugs are fixed.
Userspace should not try to use KVM_CAP_MANUAL_DIRTY_LOG_PROTECT.
7.19 KVM_CAP_PPC_SECURE_GUEST
------------------------------
:Architectures: ppc
This capability indicates that KVM is running on a host that has
ultravisor firmware and thus can support a secure guest. On such a
system, a guest can ask the ultravisor to make it a secure guest,
one whose memory is inaccessible to the host except for pages which
are explicitly requested to be shared with the host. The ultravisor
notifies KVM when a guest requests to become a secure guest, and KVM
has the opportunity to veto the transition.
If present, this capability can be enabled for a VM, meaning that KVM
will allow the transition to secure guest mode. Otherwise KVM will
veto the transition.
7.20 KVM_CAP_HALT_POLL
----------------------
:Architectures: all
:Target: VM
:Parameters: args[0] is the maximum poll time in nanoseconds
:Returns: 0 on success; -1 on error
KVM_CAP_HALT_POLL overrides the kvm.halt_poll_ns module parameter to set the
maximum halt-polling time for all vCPUs in the target VM. This capability can
be invoked at any time and any number of times to dynamically change the
maximum halt-polling time.
See Documentation/virt/kvm/halt-polling.rst for more information on halt
polling.
7.21 KVM_CAP_X86_USER_SPACE_MSR
-------------------------------
:Architectures: x86
:Target: VM
:Parameters: args[0] contains the mask of KVM_MSR_EXIT_REASON_* events to report
:Returns: 0 on success; -1 on error
This capability allows userspace to intercept RDMSR and WRMSR instructions if
access to an MSR is denied. By default, KVM injects #GP on denied accesses.
When a guest requests to read or write an MSR, KVM may not implement all MSRs
that are relevant to a respective system. It also does not differentiate by
CPU type.
To allow more fine grained control over MSR handling, userspace may enable
this capability. With it enabled, MSR accesses that match the mask specified in
args[0] and would trigger a #GP inside the guest will instead trigger
KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR exit notifications. Userspace
can then implement model specific MSR handling and/or user notifications
to inform a user that an MSR was not emulated/virtualized by KVM.
The valid mask flags are:
============================ ===============================================
KVM_MSR_EXIT_REASON_UNKNOWN intercept accesses to unknown (to KVM) MSRs
KVM_MSR_EXIT_REASON_INVAL intercept accesses that are architecturally
invalid according to the vCPU model and/or mode
KVM_MSR_EXIT_REASON_FILTER intercept accesses that are denied by userspace
via KVM_X86_SET_MSR_FILTER
============================ ===============================================
7.22 KVM_CAP_X86_BUS_LOCK_EXIT
-------------------------------
:Architectures: x86
:Target: VM
:Parameters: args[0] defines the policy used when bus locks detected in guest
:Returns: 0 on success, -EINVAL when args[0] contains invalid bits
Valid bits in args[0] are::
#define KVM_BUS_LOCK_DETECTION_OFF (1 << 0)
#define KVM_BUS_LOCK_DETECTION_EXIT (1 << 1)
Enabling this capability on a VM provides userspace with a way to select a
policy to handle the bus locks detected in guest. Userspace can obtain the
supported modes from the result of KVM_CHECK_EXTENSION and define it through
the KVM_ENABLE_CAP. The supported modes are mutually-exclusive.
This capability allows userspace to force VM exits on bus locks detected in the
guest, irrespective whether or not the host has enabled split-lock detection
(which triggers an #AC exception that KVM intercepts). This capability is
intended to mitigate attacks where a malicious/buggy guest can exploit bus
locks to degrade the performance of the whole system.
If KVM_BUS_LOCK_DETECTION_OFF is set, KVM doesn't force guest bus locks to VM
exit, although the host kernel's split-lock #AC detection still applies, if
enabled.
If KVM_BUS_LOCK_DETECTION_EXIT is set, KVM enables a CPU feature that ensures
bus locks in the guest trigger a VM exit, and KVM exits to userspace for all
such VM exits, e.g. to allow userspace to throttle the offending guest and/or
apply some other policy-based mitigation. When exiting to userspace, KVM sets
KVM_RUN_X86_BUS_LOCK in vcpu-run->flags, and conditionally sets the exit_reason
to KVM_EXIT_X86_BUS_LOCK.
Due to differences in the underlying hardware implementation, the vCPU's RIP at
the time of exit diverges between Intel and AMD. On Intel hosts, RIP points at
the next instruction, i.e. the exit is trap-like. On AMD hosts, RIP points at
the offending instruction, i.e. the exit is fault-like.
Note! Detected bus locks may be coincident with other exits to userspace, i.e.
KVM_RUN_X86_BUS_LOCK should be checked regardless of the primary exit reason if
userspace wants to take action on all detected bus locks.
7.23 KVM_CAP_PPC_DAWR1
----------------------
:Architectures: ppc
:Parameters: none
:Returns: 0 on success, -EINVAL when CPU doesn't support 2nd DAWR
This capability can be used to check / enable 2nd DAWR feature provided
by POWER10 processor.
7.24 KVM_CAP_VM_COPY_ENC_CONTEXT_FROM
-------------------------------------
:Architectures: x86 SEV enabled
:Type: vm
:Parameters: args[0] is the fd of the source vm
:Returns: 0 on success; ENOTTY on error
This capability enables userspace to copy encryption context from the vm
indicated by the fd to the vm this is called on.
This is intended to support in-guest workloads scheduled by the host. This
allows the in-guest workload to maintain its own NPTs and keeps the two vms
from accidentally clobbering each other with interrupts and the like (separate
APIC/MSRs/etc).
7.25 KVM_CAP_SGX_ATTRIBUTE
--------------------------
:Architectures: x86
:Target: VM
:Parameters: args[0] is a file handle of a SGX attribute file in securityfs
:Returns: 0 on success, -EINVAL if the file handle is invalid or if a requested
attribute is not supported by KVM.
KVM_CAP_SGX_ATTRIBUTE enables a userspace VMM to grant a VM access to one or
more privileged enclave attributes. args[0] must hold a file handle to a valid
SGX attribute file corresponding to an attribute that is supported/restricted
by KVM (currently only PROVISIONKEY).
The SGX subsystem restricts access to a subset of enclave attributes to provide
additional security for an uncompromised kernel, e.g. use of the PROVISIONKEY
is restricted to deter malware from using the PROVISIONKEY to obtain a stable
system fingerprint. To prevent userspace from circumventing such restrictions
by running an enclave in a VM, KVM prevents access to privileged attributes by
default.
See Documentation/arch/x86/sgx.rst for more details.
7.27 KVM_CAP_EXIT_ON_EMULATION_FAILURE
--------------------------------------
:Architectures: x86
:Parameters: args[0] whether the feature should be enabled or not
When this capability is enabled, an emulation failure will result in an exit
to userspace with KVM_INTERNAL_ERROR (except when the emulator was invoked
to handle a VMware backdoor instruction). Furthermore, KVM will now provide up
to 15 instruction bytes for any exit to userspace resulting from an emulation
failure. When these exits to userspace occur use the emulation_failure struct
instead of the internal struct. They both have the same layout, but the
emulation_failure struct matches the content better. It also explicitly
defines the 'flags' field which is used to describe the fields in the struct
that are valid (ie: if KVM_INTERNAL_ERROR_EMULATION_FLAG_INSTRUCTION_BYTES is
set in the 'flags' field then both 'insn_size' and 'insn_bytes' have valid data
in them.)
7.28 KVM_CAP_ARM_MTE
--------------------
:Architectures: arm64
:Parameters: none
This capability indicates that KVM (and the hardware) supports exposing the
Memory Tagging Extensions (MTE) to the guest. It must also be enabled by the
VMM before creating any VCPUs to allow the guest access. Note that MTE is only
available to a guest running in AArch64 mode and enabling this capability will
cause attempts to create AArch32 VCPUs to fail.
When enabled the guest is able to access tags associated with any memory given
to the guest. KVM will ensure that the tags are maintained during swap or
hibernation of the host; however the VMM needs to manually save/restore the
tags as appropriate if the VM is migrated.
When this capability is enabled all memory in memslots must be mapped as
``MAP_ANONYMOUS`` or with a RAM-based file mapping (``tmpfs``, ``memfd``),
attempts to create a memslot with an invalid mmap will result in an
-EINVAL return.
When enabled the VMM may make use of the ``KVM_ARM_MTE_COPY_TAGS`` ioctl to
perform a bulk copy of tags to/from the guest.
7.29 KVM_CAP_VM_MOVE_ENC_CONTEXT_FROM
-------------------------------------
:Architectures: x86 SEV enabled
:Type: vm
:Parameters: args[0] is the fd of the source vm
:Returns: 0 on success
This capability enables userspace to migrate the encryption context from the VM
indicated by the fd to the VM this is called on.
This is intended to support intra-host migration of VMs between userspace VMMs,
upgrading the VMM process without interrupting the guest.
7.31 KVM_CAP_DISABLE_QUIRKS2
----------------------------
:Parameters: args[0] - set of KVM quirks to disable
:Architectures: x86
:Type: vm
This capability, if enabled, will cause KVM to disable some behavior
quirks.
Calling KVM_CHECK_EXTENSION for this capability returns a bitmask of
quirks that can be disabled in KVM.
The argument to KVM_ENABLE_CAP for this capability is a bitmask of
quirks to disable, and must be a subset of the bitmask returned by
KVM_CHECK_EXTENSION.
The valid bits in cap.args[0] are:
=================================== ============================================
KVM_X86_QUIRK_LINT0_REENABLED By default, the reset value for the LVT
LINT0 register is 0x700 (APIC_MODE_EXTINT).
When this quirk is disabled, the reset value
is 0x10000 (APIC_LVT_MASKED).
KVM_X86_QUIRK_CD_NW_CLEARED By default, KVM clears CR0.CD and CR0.NW on
AMD CPUs to workaround buggy guest firmware
that runs in perpetuity with CR0.CD, i.e.
with caches in "no fill" mode.
When this quirk is disabled, KVM does not
change the value of CR0.CD and CR0.NW.
KVM_X86_QUIRK_LAPIC_MMIO_HOLE By default, the MMIO LAPIC interface is
available even when configured for x2APIC
mode. When this quirk is disabled, KVM
disables the MMIO LAPIC interface if the
LAPIC is in x2APIC mode.
KVM_X86_QUIRK_OUT_7E_INC_RIP By default, KVM pre-increments %rip before
exiting to userspace for an OUT instruction
to port 0x7e. When this quirk is disabled,
KVM does not pre-increment %rip before
exiting to userspace.
KVM_X86_QUIRK_MISC_ENABLE_NO_MWAIT When this quirk is disabled, KVM sets
CPUID.01H:ECX[bit 3] (MONITOR/MWAIT) if
IA32_MISC_ENABLE[bit 18] (MWAIT) is set.
Additionally, when this quirk is disabled,
KVM clears CPUID.01H:ECX[bit 3] if
IA32_MISC_ENABLE[bit 18] is cleared.
KVM_X86_QUIRK_FIX_HYPERCALL_INSN By default, KVM rewrites guest
VMMCALL/VMCALL instructions to match the
vendor's hypercall instruction for the
system. When this quirk is disabled, KVM
will no longer rewrite invalid guest
hypercall instructions. Executing the
incorrect hypercall instruction will
generate a #UD within the guest.
KVM_X86_QUIRK_MWAIT_NEVER_UD_FAULTS By default, KVM emulates MONITOR/MWAIT (if
they are intercepted) as NOPs regardless of
whether or not MONITOR/MWAIT are supported
according to guest CPUID. When this quirk
is disabled and KVM_X86_DISABLE_EXITS_MWAIT
is not set (MONITOR/MWAIT are intercepted),
KVM will inject a #UD on MONITOR/MWAIT if
they're unsupported per guest CPUID. Note,
KVM will modify MONITOR/MWAIT support in
guest CPUID on writes to MISC_ENABLE if
KVM_X86_QUIRK_MISC_ENABLE_NO_MWAIT is
disabled.
KVM_X86_QUIRK_SLOT_ZAP_ALL By default, for KVM_X86_DEFAULT_VM VMs, KVM
invalidates all SPTEs in all memslots and
address spaces when a memslot is deleted or
moved. When this quirk is disabled (or the
VM type isn't KVM_X86_DEFAULT_VM), KVM only
ensures the backing memory of the deleted
or moved memslot isn't reachable, i.e KVM
_may_ invalidate only SPTEs related to the
memslot.
KVM_X86_QUIRK_STUFF_FEATURE_MSRS By default, at vCPU creation, KVM sets the
vCPU's MSR_IA32_PERF_CAPABILITIES (0x345),
MSR_IA32_ARCH_CAPABILITIES (0x10a),
MSR_PLATFORM_INFO (0xce), and all VMX MSRs
(0x480..0x492) to the maximal capabilities
supported by KVM. KVM also sets
MSR_IA32_UCODE_REV (0x8b) to an arbitrary
value (which is different for Intel vs.
AMD). Lastly, when guest CPUID is set (by
userspace), KVM modifies select VMX MSR
fields to force consistency between guest
CPUID and L2's effective ISA. When this
quirk is disabled, KVM zeroes the vCPU's MSR
values (with two exceptions, see below),
i.e. treats the feature MSRs like CPUID
leaves and gives userspace full control of
the vCPU model definition. This quirk does
not affect VMX MSRs CR0/CR4_FIXED1 (0x487
and 0x489), as KVM does now allow them to
be set by userspace (KVM sets them based on
guest CPUID, for safety purposes).
KVM_X86_QUIRK_IGNORE_GUEST_PAT By default, on Intel platforms, KVM ignores
guest PAT and forces the effective memory
type to WB in EPT. The quirk is not available
on Intel platforms which are incapable of
safely honoring guest PAT (i.e., without CPU
self-snoop, KVM always ignores guest PAT and
forces effective memory type to WB). It is
also ignored on AMD platforms or, on Intel,
when a VM has non-coherent DMA devices
assigned; KVM always honors guest PAT in
such case. The quirk is needed to avoid
slowdowns on certain Intel Xeon platforms
(e.g. ICX, SPR) where self-snoop feature is
supported but UC is slow enough to cause
issues with some older guests that use
UC instead of WC to map the video RAM.
Userspace can disable the quirk to honor
guest PAT if it knows that there is no such
guest software, for example if it does not
expose a bochs graphics device (which is
known to have had a buggy driver).
KVM_X86_QUIRK_VMCS12_ALLOW_FREEZE_IN_SMM By default, KVM relaxes the consistency
check for GUEST_IA32_DEBUGCTL in vmcs12
to allow FREEZE_IN_SMM to be set. When
this quirk is disabled, KVM requires this
bit to be cleared. Note that the vmcs02
bit is still completely controlled by the
host, regardless of the quirk setting.
=================================== ============================================
7.32 KVM_CAP_MAX_VCPU_ID
------------------------
:Architectures: x86
:Target: VM
:Parameters: args[0] - maximum APIC ID value set for current VM
:Returns: 0 on success, -EINVAL if args[0] is beyond KVM_MAX_VCPU_IDS
supported in KVM or if it has been set.
This capability allows userspace to specify maximum possible APIC ID
assigned for current VM session prior to the creation of vCPUs, saving
memory for data structures indexed by the APIC ID. Userspace is able
to calculate the limit to APIC ID values from designated
CPU topology.
The value can be changed only until KVM_ENABLE_CAP is set to a nonzero
value or until a vCPU is created. Upon creation of the first vCPU,
if the value was set to zero or KVM_ENABLE_CAP was not invoked, KVM
uses the return value of KVM_CHECK_EXTENSION(KVM_CAP_MAX_VCPU_ID) as
the maximum APIC ID.
7.33 KVM_CAP_X86_NOTIFY_VMEXIT
------------------------------
:Architectures: x86
:Target: VM
:Parameters: args[0] is the value of notify window as well as some flags
:Returns: 0 on success, -EINVAL if args[0] contains invalid flags or notify
VM exit is unsupported.
Bits 63:32 of args[0] are used for notify window.
Bits 31:0 of args[0] are for some flags. Valid bits are::
#define KVM_X86_NOTIFY_VMEXIT_ENABLED (1 << 0)
#define KVM_X86_NOTIFY_VMEXIT_USER (1 << 1)
This capability allows userspace to configure the notify VM exit on/off
in per-VM scope during VM creation. Notify VM exit is disabled by default.
When userspace sets KVM_X86_NOTIFY_VMEXIT_ENABLED bit in args[0], VMM will
enable this feature with the notify window provided, which will generate
a VM exit if no event window occurs in VM non-root mode for a specified of
time (notify window).
If KVM_X86_NOTIFY_VMEXIT_USER is set in args[0], upon notify VM exits happen,
KVM would exit to userspace for handling.
This capability is aimed to mitigate the threat that malicious VMs can
cause CPU stuck (due to event windows don't open up) and make the CPU
unavailable to host or other VMs.
7.35 KVM_CAP_X86_APIC_BUS_CYCLES_NS
-----------------------------------
:Architectures: x86
:Target: VM
:Parameters: args[0] is the desired APIC bus clock rate, in nanoseconds
:Returns: 0 on success, -EINVAL if args[0] contains an invalid value for the
frequency or if any vCPUs have been created, -ENXIO if a virtual
local APIC has not been created using KVM_CREATE_IRQCHIP.
This capability sets the VM's APIC bus clock frequency, used by KVM's in-kernel
virtual APIC when emulating APIC timers. KVM's default value can be retrieved
by KVM_CHECK_EXTENSION.
Note: Userspace is responsible for correctly configuring CPUID 0x15, a.k.a. the
core crystal clock frequency, if a non-zero CPUID 0x15 is exposed to the guest.
7.36 KVM_CAP_DIRTY_LOG_RING/KVM_CAP_DIRTY_LOG_RING_ACQ_REL
----------------------------------------------------------
:Architectures: x86, arm64, riscv
:Type: vm
:Parameters: args[0] - size of the dirty log ring
KVM is capable of tracking dirty memory using ring buffers that are
mmapped into userspace; there is one dirty ring per vcpu.
The dirty ring is available to userspace as an array of
``struct kvm_dirty_gfn``. Each dirty entry is defined as::
struct kvm_dirty_gfn {
__u32 flags;
__u32 slot; /* as_id | slot_id */
__u64 offset;
};
The following values are defined for the flags field to define the
current state of the entry::
#define KVM_DIRTY_GFN_F_DIRTY BIT(0)
#define KVM_DIRTY_GFN_F_RESET BIT(1)
#define KVM_DIRTY_GFN_F_MASK 0x3
Userspace should call KVM_ENABLE_CAP ioctl right after KVM_CREATE_VM
ioctl to enable this capability for the new guest and set the size of
the rings. Enabling the capability is only allowed before creating any
vCPU, and the size of the ring must be a power of two. The larger the
ring buffer, the less likely the ring is full and the VM is forced to
exit to userspace. The optimal size depends on the workload, but it is
recommended that it be at least 64 KiB (4096 entries).
Just like for dirty page bitmaps, the buffer tracks writes to
all user memory regions for which the KVM_MEM_LOG_DIRTY_PAGES flag was
set in KVM_SET_USER_MEMORY_REGION. Once a memory region is registered
with the flag set, userspace can start harvesting dirty pages from the
ring buffer.
An entry in the ring buffer can be unused (flag bits ``00``),
dirty (flag bits ``01``) or harvested (flag bits ``1X``). The
state machine for the entry is as follows::
dirtied harvested reset
00 -----------> 01 -------------> 1X -------+
^ |
| |
+------------------------------------------+
To harvest the dirty pages, userspace accesses the mmapped ring buffer
to read the dirty GFNs. If the flags has the DIRTY bit set (at this stage
the RESET bit must be cleared), then it means this GFN is a dirty GFN.
The userspace should harvest this GFN and mark the flags from state
``01b`` to ``1Xb`` (bit 0 will be ignored by KVM, but bit 1 must be set
to show that this GFN is harvested and waiting for a reset), and move
on to the next GFN. The userspace should continue to do this until the
flags of a GFN have the DIRTY bit cleared, meaning that it has harvested
all the dirty GFNs that were available.
Note that on weakly ordered architectures, userspace accesses to the
ring buffer (and more specifically the 'flags' field) must be ordered,
using load-acquire/store-release accessors when available, or any
other memory barrier that will ensure this ordering.
It's not necessary for userspace to harvest the all dirty GFNs at once.
However it must collect the dirty GFNs in sequence, i.e., the userspace
program cannot skip one dirty GFN to collect the one next to it.
After processing one or more entries in the ring buffer, userspace
calls the VM ioctl KVM_RESET_DIRTY_RINGS to notify the kernel about
it, so that the kernel will reprotect those collected GFNs.
Therefore, the ioctl must be called *before* reading the content of
the dirty pages.
The dirty ring can get full. When it happens, the KVM_RUN of the
vcpu will return with exit reason KVM_EXIT_DIRTY_LOG_FULL.
The dirty ring interface has a major difference comparing to the
KVM_GET_DIRTY_LOG interface in that, when reading the dirty ring from
userspace, it's still possible that the kernel has not yet flushed the
processor's dirty page buffers into the kernel buffer (with dirty bitmaps, the
flushing is done by the KVM_GET_DIRTY_LOG ioctl). To achieve that, one
needs to kick the vcpu out of KVM_RUN using a signal. The resulting
vmexit ensures that all dirty GFNs are flushed to the dirty rings.
NOTE: KVM_CAP_DIRTY_LOG_RING_ACQ_REL is the only capability that
should be exposed by weakly ordered architecture, in order to indicate
the additional memory ordering requirements imposed on userspace when
reading the state of an entry and mutating it from DIRTY to HARVESTED.
Architecture with TSO-like ordering (such as x86) are allowed to
expose both KVM_CAP_DIRTY_LOG_RING and KVM_CAP_DIRTY_LOG_RING_ACQ_REL
to userspace.
After enabling the dirty rings, the userspace needs to detect the
capability of KVM_CAP_DIRTY_LOG_RING_WITH_BITMAP to see whether the
ring structures can be backed by per-slot bitmaps. With this capability
advertised, it means the architecture can dirty guest pages without
vcpu/ring context, so that some of the dirty information will still be
maintained in the bitmap structure. KVM_CAP_DIRTY_LOG_RING_WITH_BITMAP
can't be enabled if the capability of KVM_CAP_DIRTY_LOG_RING_ACQ_REL
hasn't been enabled, or any memslot has been existing.
Note that the bitmap here is only a backup of the ring structure. The
use of the ring and bitmap combination is only beneficial if there is
only a very small amount of memory that is dirtied out of vcpu/ring
context. Otherwise, the stand-alone per-slot bitmap mechanism needs to
be considered.
To collect dirty bits in the backup bitmap, userspace can use the same
KVM_GET_DIRTY_LOG ioctl. KVM_CLEAR_DIRTY_LOG isn't needed as long as all
the generation of the dirty bits is done in a single pass. Collecting
the dirty bitmap should be the very last thing that the VMM does before
considering the state as complete. VMM needs to ensure that the dirty
state is final and avoid missing dirty pages from another ioctl ordered
after the bitmap collection.
NOTE: Multiple examples of using the backup bitmap: (1) save vgic/its
tables through command KVM_DEV_ARM_{VGIC_GRP_CTRL, ITS_SAVE_TABLES} on
KVM device "kvm-arm-vgic-its". (2) restore vgic/its tables through
command KVM_DEV_ARM_{VGIC_GRP_CTRL, ITS_RESTORE_TABLES} on KVM device
"kvm-arm-vgic-its". VGICv3 LPI pending status is restored. (3) save
vgic3 pending table through KVM_DEV_ARM_VGIC_{GRP_CTRL, SAVE_PENDING_TABLES}
command on KVM device "kvm-arm-vgic-v3".
7.37 KVM_CAP_PMU_CAPABILITY
---------------------------
:Architectures: x86
:Type: vm
:Parameters: arg[0] is bitmask of PMU virtualization capabilities.
:Returns: 0 on success, -EINVAL when arg[0] contains invalid bits
This capability alters PMU virtualization in KVM.
Calling KVM_CHECK_EXTENSION for this capability returns a bitmask of
PMU virtualization capabilities that can be adjusted on a VM.
The argument to KVM_ENABLE_CAP is also a bitmask and selects specific
PMU virtualization capabilities to be applied to the VM. This can
only be invoked on a VM prior to the creation of VCPUs.
At this time, KVM_PMU_CAP_DISABLE is the only capability. Setting
this capability will disable PMU virtualization for that VM. Usermode
should adjust CPUID leaf 0xA to reflect that the PMU is disabled.
7.38 KVM_CAP_VM_DISABLE_NX_HUGE_PAGES
-------------------------------------
:Architectures: x86
:Type: vm
:Parameters: arg[0] must be 0.
:Returns: 0 on success, -EPERM if the userspace process does not
have CAP_SYS_BOOT, -EINVAL if args[0] is not 0 or any vCPUs have been
created.
This capability disables the NX huge pages mitigation for iTLB MULTIHIT.
The capability has no effect if the nx_huge_pages module parameter is not set.
This capability may only be set before any vCPUs are created.
7.39 KVM_CAP_ARM_EAGER_SPLIT_CHUNK_SIZE
---------------------------------------
:Architectures: arm64
:Type: vm
:Parameters: arg[0] is the new split chunk size.
:Returns: 0 on success, -EINVAL if any memslot was already created.
This capability sets the chunk size used in Eager Page Splitting.
Eager Page Splitting improves the performance of dirty-logging (used
in live migrations) when guest memory is backed by huge-pages. It
avoids splitting huge-pages (into PAGE_SIZE pages) on fault, by doing
it eagerly when enabling dirty logging (with the
KVM_MEM_LOG_DIRTY_PAGES flag for a memory region), or when using
KVM_CLEAR_DIRTY_LOG.
The chunk size specifies how many pages to break at a time, using a
single allocation for each chunk. Bigger the chunk size, more pages
need to be allocated ahead of time.
The chunk size needs to be a valid block size. The list of acceptable
block sizes is exposed in KVM_CAP_ARM_SUPPORTED_BLOCK_SIZES as a
64-bit bitmap (each bit describing a block size). The default value is
0, to disable the eager page splitting.
7.40 KVM_CAP_EXIT_HYPERCALL
---------------------------
:Architectures: x86
:Type: vm
This capability, if enabled, will cause KVM to exit to userspace
with KVM_EXIT_HYPERCALL exit reason to process some hypercalls.
Calling KVM_CHECK_EXTENSION for this capability will return a bitmask
of hypercalls that can be configured to exit to userspace.
Right now, the only such hypercall is KVM_HC_MAP_GPA_RANGE.
The argument to KVM_ENABLE_CAP is also a bitmask, and must be a subset
of the result of KVM_CHECK_EXTENSION. KVM will forward to userspace
the hypercalls whose corresponding bit is in the argument, and return
ENOSYS for the others.
7.41 KVM_CAP_ARM_SYSTEM_SUSPEND
-------------------------------
:Architectures: arm64
:Type: vm
When enabled, KVM will exit to userspace with KVM_EXIT_SYSTEM_EVENT of
type KVM_SYSTEM_EVENT_SUSPEND to process the guest suspend request.
7.42 KVM_CAP_ARM_WRITABLE_IMP_ID_REGS
-------------------------------------
:Architectures: arm64
:Target: VM
:Parameters: None
:Returns: 0 on success, -EINVAL if vCPUs have been created before enabling this
capability.
This capability changes the behavior of the registers that identify a PE
implementation of the Arm architecture: MIDR_EL1, REVIDR_EL1, and AIDR_EL1.
By default, these registers are visible to userspace but treated as invariant.
When this capability is enabled, KVM allows userspace to change the
aforementioned registers before the first KVM_RUN. These registers are VM
scoped, meaning that the same set of values are presented on all vCPUs in a
given VM.
7.43 KVM_CAP_RISCV_MP_STATE_RESET
---------------------------------
:Architectures: riscv
:Type: VM
:Parameters: None
:Returns: 0 on success, -EINVAL if arg[0] is not zero
When this capability is enabled, KVM resets the VCPU when setting
MP_STATE_INIT_RECEIVED through IOCTL. The original MP_STATE is preserved.
7.43과 8. 기타 capability
8727-9263arm64의 두 번째 7.43 항목인 `KVM_CAP_ARM_CACHEABLE_PFNMAP_SUPPORTED`는 PFNMAP memory region을 cacheable로 안전하게 mapping할 수 있는지를 userspace에 알립니다. 이 보장은 hardware의 force write back(FWB) feature 지원에 의존합니다.
8장은 VM이나 vCPU에 직접 enable하는 기능뿐 아니라 현재 KVM 구현과 host가 제공하는 architecture별 능력을 조회하는 capability를 모읍니다. 반환값이 단순 boolean이 아닌 경우에는 알려진 값이나 bitmap을 기준으로 해석하고 예약값을 임의로 사용하지 않아야 합니다.
Capability의미
`KVM_CAP_PPC_HWRNG`Hardware RNG 기반 `H_RANDOM` hypercall 구현. Guest가 쓰게 하려면 `KVM_CAP_PPC_ENABLE_HCALL`로 handler를 enable
`KVM_CAP_PPC_MMU_RADIX`POWER9에 구현된 Power ISA V3.00 radix MMU guest 지원
`KVM_CAP_PPC_MMU_HASH_V3`In-memory segment table을 포함한 Power ISA V3.00 hashed-page-table MMU 지원
`KVM_CAP_PPC_SMT_POSSIBLE`Bit N이 set이면 `KVM_CAP_PPC_SMT`로 virtual SMT mode `2^N` 설정 가능
`KVM_CAP_SPAPR_MULTITCE``H_PUT_TCE_INDIRECT`와 `H_STUFF_TCE` kernel fast path. 항상 enable되지만 실패하면 userspace handler로 fallback
`KVM_CAP_PPC_RPT_INVALIDATE`Radix MMU를 지원하는 POWER9 계열 hypervisor의 `H_RPT_INVALIDATE` 처리
`KVM_CAP_PPC_AIL_MODE_3``H_SET_MODE`로 제어하는 Address Translation Mode on Interrupt의 mode 3 지원
MMU mode, SMT, hypercall acceleration과 interrupt mode 지원을 확인합니다.
sPAPR guest가 multi-TCE나 RPT invalidate hypercall을 사용하려면 VMM이 device tree의 `ibm,hypertas-functions`에 각각 `hcall-multi-tce`, `hcall-rpt-invalidate`를 광고해야 할 수 있습니다. LIOBN을 KVM에 등록한 뒤 multi-TCE fast path가 성공하면 userspace hypercall handler는 호출되지 않지만, kernel이 처리하지 못한 경우를 위해 handler 자체는 유지해야 합니다.
`KVM_CAP_PPC_AIL_MODE_3`은 interrupt와 system call 처리에 더 나은 성능의 alternate interrupt location을 guest kernel이 선택하게 합니다.
값`KVM_CAP_MIPS_VZ` 의미
0Trap-and-emulate 구현. Guest code를 user mode에서 실행하고 virtual memory segment를 user address space에 맞게 재배치
1MIPS VZ ASE를 사용한 full hardware-assisted virtualization과 표준 guest virtual memory segment
`KVM_CAP_MIPS_VZ`는 main KVM fd와 VM fd에서 의미가 다르며 알려진 반환값만 사용해야 합니다.
Main KVM fd에서 `KVM_CAP_MIPS_VZ`를 조회하면 해당 hardware-assisted VM type을 만들 수 있음을 뜻하며 `KVM_CREATE_VM`에 알맞은 `KVM_VM_MIPS_*` type을 전달해야 합니다. VM fd 조회는 이미 만든 VM이 full hardware assistance를 쓰는지 확인하며 특히 `KVM_VM_MIPS_DEFAULT` 뒤에 유용합니다.
값지원 architecture
0MIPS32 또는 microMIPS32. Register와 address 모두 32-bit이며 32-bit guest code만 실행
1MIPS64 또는 microMIPS64 compatibility segment. Register는 64-bit, address는 32-bit이며 32-bit와 제한된 64-bit code 실행
2모든 MIPS64 address segment. Register와 address 모두 64-bit이며 64-bit와 32-bit guest code 실행
`KVM_CAP_MIPS_64BIT` 반환값은 대체로 `CP0_Config.AT`와 대응하며 그 밖의 값은 예약됩니다.
`KVM_CAP_ARM_USER_IRQ`는 in-kernel interrupt controller 없이 만든 arm64 VM에서 emulated device output level 변화를 userspace에 통지합니다. Kernel은 userspace로 돌아올 때마다 `run->s.regs.device_irq_level`을 실제 output level로 갱신하며, 변화가 있으면 guest를 다시 실행하기 전에 최소 한 번 exit를 보장합니다.
통지는 `KVM_EXIT_INTR`일 수도 있고 `KVM_EXIT_MMIO` 같은 다른 exit일 수도 있으므로 userspace는 모든 KVM exit에서 `device_irq_level`을 검사해 userspace interrupt controller 상태를 다시 계산해야 합니다. Level-triggered와 edge-triggered signal을 모두 나타내며 edge는 edge마다 정확히 한 exit에서 bit가 set됩니다.
`device_irq_level`은 `kvm_valid_regs`나 `kvm_dirty_regs`와 독립적으로 유효합니다. Capability 조회의 양수 반환값은 version이며 현재 version 1은 아래 signal bit를 정의합니다.
BitDevice output
`KVM_ARM_DEV_EL1_VTIMER`EL1 virtual timer
`KVM_ARM_DEV_EL1_PTIMER`EL1 physical timer
`KVM_ARM_DEV_PMU`ARM PMU overflow interrupt signal
향후 version은 더 큰 반환값과 새 bit를 추가할 수 있습니다.
`KVM_CAP_ARM_INJECT_SERROR_ESR`은 `KVM_SET_VCPU_EVENTS`로 virtual SError의 syndrome을 지정하게 합니다. Userspace가 정할 수 있는 것은 ESR의 ISS field뿐이며 EC 같은 나머지 field는 exception을 받을 때 CPU가 생성합니다. AArch64 EL1로 전달되면 값은 `ESR_ELx.ISS`에 보입니다.
`KVM_CAP_PTP_KVM`은 host의 KVM virtual PTP service 지원을 나타내며 VMM은 migration 때 destination에서도 guest service가 가능한지 확인할 수 있습니다.
`KVM_CAP_STEAL_TIME`은 arm64와 x86의 steal-time accounting 지원을 뜻합니다. Architecture-specific interface와 capability 결과는 서로 일치해야 하며 arm64는 `KVM_ARM_VCPU_PVTIME_CTRL`, x86은 `MSR_KVM_STEAL_TIME` 계약을 따릅니다.
Capability의미
`KVM_CAP_S390_AIS_MIGRATION`FLIC device 생성 없이 `KVM_DEV_FLIC_AISM_ALL`로 AIS state get/set 가능 여부 확인
`KVM_CAP_S390_PSW`PSW를 `kvm_run` 구조에 노출
`KVM_CAP_S390_GMAP`Memslot이 1MiB segment 경계에 정렬되고 그 배수 크기이면 userspace 어디든 guest mapping 가능
`KVM_CAP_S390_COW`Guest mapping에 copy-on-write와 read-only page table 기반 dirty tracking 허용
`KVM_CAP_S390_BPB`Branch prediction blocking의 reset, migration, nested KVM interface 지원
`KVM_CAP_S390_VCPU_RESETS``KVM_S390_NORMAL_RESET`과 `KVM_S390_CLEAR_RESET` ioctl 제공
Migration, guest mapping과 branch-prediction state를 다루는 기본 capability입니다.
Guest에 STFLE facility 82를 제공하려면 `KVM_CAP_S390_BPB`도 반드시 있어야 합니다. Facility 광고와 KVM의 reset·migration·nested 처리 능력이 불일치하면 branch-prediction blocking state를 올바르게 유지할 수 없습니다.
Capability의미
`KVM_CAP_S390_PROTECTED`Ultravisor 초기화 완료와 protected VM 시작 가능. `KVM_S390_PV_COMMAND`, `KVM_MP_STATE_LOAD`를 관할
`KVM_CAP_S390_PROTECTED_DUMP``KVM_PV_DUMP`, `KVM_PV_INFO`, vCPU `KVM_S390_PV_CPU_COMMAND`의 `KVM_PV_DUMP_CPU` 지원
`KVM_CAP_S390_DIAG318`DIAGNOSE 0x318의 CPNC 1-byte와 CPVC 7-byte를 guest가 설정하고 `KVM_SYNC_DIAG318`로 동기화
`KVM_CAP_S390_CPU_TOPOLOGY`PTF function 2 해석, PTF 0/1과 `STSI(15,1,x)` userspace 전달, SCA MTCR bit attribute 제공
Ultravisor 기능, CPU topology와 guest control-program 정보를 다룹니다.
Protected guest에서는 invalid MP-state transition 때문에 `KVM_SET_MP_STATE`가 실패할 수 있습니다. Protected dump capability가 있으면 PV guest dump 관련 VM command뿐 아니라 vCPU별 dump command도 사용할 수 있습니다.
DIAGNOSE 0x318의 CPNC는 Linux, z/VM 같은 control-program 환경을 식별하고 CPVC는 OS version이나 distribution 같은 세부 정보를 담습니다. Firmware와 system service event에서 실행 중인 guest 환경을 식별하는 데 쓰입니다.
s390 CPU topology capability가 있을 때 VM fd의 `KVM_S390_VM_CPU_TOPOLOGY` attribute group으로 SCA의 Modified Change Topology Report(MTCR) bit를 get, set, clear할 수 있습니다. Get 작업의 `attr->addr`는 값을 저장할 byte를 가리켜야 하며 capability 없이 STFLE facility 11을 guest에 광고해서는 안 됩니다.
Capability의미
`KVM_CAP_HYPERV_VP_INDEX`Userspace가 `HV_X64_MSR_VP_INDEX`를 load해 SynIC interrupt target vCPU를 지정. 기본값은 KVM 내부 vCPU index
`KVM_CAP_HYPERV_TLBFLUSH``HvFlushVirtualAddressSpace/List`와 Ex variant paravirtualized hypercall 지원
`KVM_CAP_HYPERV_SEND_IPI``HvCallSendSyntheticClusterIpi`와 Ex variant 지원
`KVM_CAP_X86_USER_SPACE_MSR`KVM이 보통 guest `#GP`로 처리할 MSR read/write를 `KVM_EXIT_X86_RDMSR/WRMSR`로 deflect
`KVM_CAP_X86_MSR_FILTER``KVM_X86_SET_MSR_FILTER`로 MSR range bitmap을 지정해 access 거부
Synthetic interrupt, TLB/IPI hypercall과 userspace MSR 정책을 나타냅니다.
VP index capability가 없더라도 userspace는 `HV_X64_MSR_VP_INDEX` 값을 조회할 수 있습니다. MSR filter와 userspace MSR exit를 조합하면 KVM 범위 밖 MSR을 userspace가 emulate하면서 KVM MSR emulation attack surface도 줄일 수 있습니다.
Flag지원 기능
`KVM_XEN_HVM_CONFIG_HYPERCALL_MSR`Guest hypercall page를 설정하는 `KVM_XEN_HVM_CONFIG` ioctl
`KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL`KVM이 hypercall page를 자동 생성하고 guest hypercall을 `KVM_EXIT_XEN`으로 intercept
`KVM_XEN_HVM_CONFIG_SHARED_INFO`VM/vCPU ATTR ioctl, shared-info와 event-channel upcall exception vector 전달
`KVM_XEN_HVM_CONFIG_RUNSTATE`RUNSTATE address, current, data, adjust vCPU attribute
`KVM_XEN_HVM_CONFIG_EVTCHN_2LEVEL`Priority로 2-level delivery를 표시하는 `KVM_IRQ_ROUTING_XEN_EVTCHN` route
`KVM_XEN_HVM_CONFIG_EVTCHN_SEND``KVM_XEN_HVM_EVTCHN_SEND`, event-channel·Xen-version VM attribute와 vCPU ID·timer·upcall-vector attribute
`KVM_XEN_HVM_CONFIG_RUNSTATE_UPDATE_FLAG`Guest runstate update 중 `XEN_RUNSTATE_UPDATE` bit 사용을 attribute로 명시적으로 제어
`KVM_XEN_HVM_CONFIG_PVCLOCK_TSC_UNSTABLE`Xen pvclock source의 `PVCLOCK_TSC_STABLE_BIT` clear 지원
Xen PVHVM guest를 위한 지원 기능 bitmap입니다.
`INTERCEPT_HCALL`을 `KVM_XEN_HVM_CONFIG`에도 전달하면 hypercall page 내용을 userspace가 제공하지 않아도 KVM이 생성합니다. `SHARED_INFO`는 `evtchn_upcall_pending`이 set될 때 exception-vector delivery까지 포함합니다.
구형 KVM이 RUNSTATE는 지원하지만 RUNSTATE_UPDATE_FLAG는 지원하지 않으면 guest 구조 갱신 때 항상 `XEN_RUNSTATE_UPDATE`를 set합니다. 새 flag가 있으면 guest hypercall을 받은 VMM이 해당 attribute를 enable한 뒤에만 bit를 사용하므로 userspace는 두 동작을 구분해야 합니다.
Capability의미
`KVM_CAP_VM_TYPES`Bit N이 set이면 값 N인 x86 VM type 지원: DEFAULT, SW_PROTECTED, SEV, SEV_ES
`KVM_CAP_MEMORY_FAULT_INFO`해결할 수 없는 guest page-fault VM-exit의 `kvm_run.memory_fault` annotation
`KVM_CAP_X86_GUEST_MODE`Exit 당시 nested guest code 실행 여부를 `KVM_RUN_X86_GUEST_MODE` bit로 표시
VM type, fault annotation과 nested-guest exit context를 확인합니다.
`KVM_X86_SW_PROTECTED_VM`은 개발과 시험 전용이며 effective ABI와 동작이 불안정하므로 실제 VM, 특히 production에 사용하면 안 됩니다.
`kvm_run.memory_fault`는 `KVM_RUN`이 `EFAULT` 또는 `EHWPOISON`으로 실패하고 동시에 `exit_reason == KVM_EXIT_MEMORY_FAULT`일 때만 유효합니다. Fault를 해결하고 retry하는 userspace는 같은 annotated fault가 반복되는 상황을 막아야 합니다.
Nested virtualization exit에서는 당시 실행 주체에 따라 L1 또는 L2 register state가 반환됩니다. `KVM_CAP_X86_GUEST_MODE`가 있으면 userspace는 `kvm_run.flags`의 guest-mode bit로 두 경우를 구분해야 합니다.
7.43 KVM_CAP_ARM_CACHEABLE_PFNMAP_SUPPORTED
-------------------------------------------
:Architectures: arm64
:Target: VM
:Parameters: None
This capability indicate to the userspace whether a PFNMAP memory region
can be safely mapped as cacheable. This relies on the presence of
force write back (FWB) feature support on the hardware.
8. Other capabilities.
======================
This section lists capabilities that give information about other
features of the KVM implementation.
8.1 KVM_CAP_PPC_HWRNG
---------------------
:Architectures: ppc
This capability, if KVM_CHECK_EXTENSION indicates that it is
available, means that the kernel has an implementation of the
H_RANDOM hypercall backed by a hardware random-number generator.
If present, the kernel H_RANDOM handler can be enabled for guest use
with the KVM_CAP_PPC_ENABLE_HCALL capability.
8.3 KVM_CAP_PPC_MMU_RADIX
-------------------------
:Architectures: ppc
This capability, if KVM_CHECK_EXTENSION indicates that it is
available, means that the kernel can support guests using the
radix MMU defined in Power ISA V3.00 (as implemented in the POWER9
processor).
8.4 KVM_CAP_PPC_MMU_HASH_V3
---------------------------
:Architectures: ppc
This capability, if KVM_CHECK_EXTENSION indicates that it is
available, means that the kernel can support guests using the
hashed page table MMU defined in Power ISA V3.00 (as implemented in
the POWER9 processor), including in-memory segment tables.
8.5 KVM_CAP_MIPS_VZ
-------------------
:Architectures: mips
This capability, if KVM_CHECK_EXTENSION on the main kvm handle indicates that
it is available, means that full hardware assisted virtualization capabilities
of the hardware are available for use through KVM. An appropriate
KVM_VM_MIPS_* type must be passed to KVM_CREATE_VM to create a VM which
utilises it.
If KVM_CHECK_EXTENSION on a kvm VM handle indicates that this capability is
available, it means that the VM is using full hardware assisted virtualization
capabilities of the hardware. This is useful to check after creating a VM with
KVM_VM_MIPS_DEFAULT.
The value returned by KVM_CHECK_EXTENSION should be compared against known
values (see below). All other values are reserved. This is to allow for the
possibility of other hardware assisted virtualization implementations which
may be incompatible with the MIPS VZ ASE.
== ==========================================================================
0 The trap & emulate implementation is in use to run guest code in user
mode. Guest virtual memory segments are rearranged to fit the guest in the
user mode address space.
1 The MIPS VZ ASE is in use, providing full hardware assisted
virtualization, including standard guest virtual memory segments.
== ==========================================================================
8.7 KVM_CAP_MIPS_64BIT
----------------------
:Architectures: mips
This capability indicates the supported architecture type of the guest, i.e. the
supported register and address width.
The values returned when this capability is checked by KVM_CHECK_EXTENSION on a
kvm VM handle correspond roughly to the CP0_Config.AT register field, and should
be checked specifically against known values (see below). All other values are
reserved.
== ========================================================================
0 MIPS32 or microMIPS32.
Both registers and addresses are 32-bits wide.
It will only be possible to run 32-bit guest code.
1 MIPS64 or microMIPS64 with access only to 32-bit compatibility segments.
Registers are 64-bits wide, but addresses are 32-bits wide.
64-bit guest code may run but cannot access MIPS64 memory segments.
It will also be possible to run 32-bit guest code.
2 MIPS64 or microMIPS64 with access to all address segments.
Both registers and addresses are 64-bits wide.
It will be possible to run 64-bit or 32-bit guest code.
== ========================================================================
8.9 KVM_CAP_ARM_USER_IRQ
------------------------
:Architectures: arm64
This capability, if KVM_CHECK_EXTENSION indicates that it is available, means
that if userspace creates a VM without an in-kernel interrupt controller, it
will be notified of changes to the output level of in-kernel emulated devices,
which can generate virtual interrupts, presented to the VM.
For such VMs, on every return to userspace, the kernel
updates the vcpu's run->s.regs.device_irq_level field to represent the actual
output level of the device.
Whenever kvm detects a change in the device output level, kvm guarantees at
least one return to userspace before running the VM. This exit could either
be a KVM_EXIT_INTR or any other exit event, like KVM_EXIT_MMIO. This way,
userspace can always sample the device output level and re-compute the state of
the userspace interrupt controller. Userspace should always check the state
of run->s.regs.device_irq_level on every kvm exit.
The value in run->s.regs.device_irq_level can represent both level and edge
triggered interrupt signals, depending on the device. Edge triggered interrupt
signals will exit to userspace with the bit in run->s.regs.device_irq_level
set exactly once per edge signal.
The field run->s.regs.device_irq_level is available independent of
run->kvm_valid_regs or run->kvm_dirty_regs bits.
If KVM_CAP_ARM_USER_IRQ is supported, the KVM_CHECK_EXTENSION ioctl returns a
number larger than 0 indicating the version of this capability is implemented
and thereby which bits in run->s.regs.device_irq_level can signal values.
Currently the following bits are defined for the device_irq_level bitmap::
KVM_CAP_ARM_USER_IRQ >= 1:
KVM_ARM_DEV_EL1_VTIMER - EL1 virtual timer
KVM_ARM_DEV_EL1_PTIMER - EL1 physical timer
KVM_ARM_DEV_PMU - ARM PMU overflow interrupt signal
Future versions of kvm may implement additional events. These will get
indicated by returning a higher number from KVM_CHECK_EXTENSION and will be
listed above.
8.10 KVM_CAP_PPC_SMT_POSSIBLE
-----------------------------
:Architectures: ppc
Querying this capability returns a bitmap indicating the possible
virtual SMT modes that can be set using KVM_CAP_PPC_SMT. If bit N
(counting from the right) is set, then a virtual SMT mode of 2^N is
available.
8.12 KVM_CAP_HYPERV_VP_INDEX
----------------------------
:Architectures: x86
This capability indicates that userspace can load HV_X64_MSR_VP_INDEX msr. Its
value is used to denote the target vcpu for a SynIC interrupt. For
compatibility, KVM initializes this msr to KVM's internal vcpu index. When this
capability is absent, userspace can still query this msr's value.
8.13 KVM_CAP_S390_AIS_MIGRATION
-------------------------------
:Architectures: s390
This capability indicates if the flic device will be able to get/set the
AIS states for migration via the KVM_DEV_FLIC_AISM_ALL attribute and allows
to discover this without having to create a flic device.
8.14 KVM_CAP_S390_PSW
---------------------
:Architectures: s390
This capability indicates that the PSW is exposed via the kvm_run structure.
8.15 KVM_CAP_S390_GMAP
----------------------
:Architectures: s390
This capability indicates that the user space memory used as guest mapping can
be anywhere in the user memory address space, as long as the memory slots are
aligned and sized to a segment (1MB) boundary.
8.16 KVM_CAP_S390_COW
---------------------
:Architectures: s390
This capability indicates that the user space memory used as guest mapping can
use copy-on-write semantics as well as dirty pages tracking via read-only page
tables.
8.17 KVM_CAP_S390_BPB
---------------------
:Architectures: s390
This capability indicates that kvm will implement the interfaces to handle
reset, migration and nested KVM for branch prediction blocking. The stfle
facility 82 should not be provided to the guest without this capability.
8.18 KVM_CAP_HYPERV_TLBFLUSH
----------------------------
:Architectures: x86
This capability indicates that KVM supports paravirtualized Hyper-V TLB Flush
hypercalls:
HvFlushVirtualAddressSpace, HvFlushVirtualAddressSpaceEx,
HvFlushVirtualAddressList, HvFlushVirtualAddressListEx.
8.19 KVM_CAP_ARM_INJECT_SERROR_ESR
----------------------------------
:Architectures: arm64
This capability indicates that userspace can specify (via the
KVM_SET_VCPU_EVENTS ioctl) the syndrome value reported to the guest when it
takes a virtual SError interrupt exception.
If KVM advertises this capability, userspace can only specify the ISS field for
the ESR syndrome. Other parts of the ESR, such as the EC are generated by the
CPU when the exception is taken. If this virtual SError is taken to EL1 using
AArch64, this value will be reported in the ISS field of ESR_ELx.
See KVM_CAP_VCPU_EVENTS for more details.
8.20 KVM_CAP_HYPERV_SEND_IPI
----------------------------
:Architectures: x86
This capability indicates that KVM supports paravirtualized Hyper-V IPI send
hypercalls:
HvCallSendSyntheticClusterIpi, HvCallSendSyntheticClusterIpiEx.
8.22 KVM_CAP_S390_VCPU_RESETS
-----------------------------
:Architectures: s390
This capability indicates that the KVM_S390_NORMAL_RESET and
KVM_S390_CLEAR_RESET ioctls are available.
8.23 KVM_CAP_S390_PROTECTED
---------------------------
:Architectures: s390
This capability indicates that the Ultravisor has been initialized and
KVM can therefore start protected VMs.
This capability governs the KVM_S390_PV_COMMAND ioctl and the
KVM_MP_STATE_LOAD MP_STATE. KVM_SET_MP_STATE can fail for protected
guests when the state change is invalid.
8.24 KVM_CAP_STEAL_TIME
-----------------------
:Architectures: arm64, x86
This capability indicates that KVM supports steal time accounting.
When steal time accounting is supported it may be enabled with
architecture-specific interfaces. This capability and the architecture-
specific interfaces must be consistent, i.e. if one says the feature
is supported, than the other should as well and vice versa. For arm64
see Documentation/virt/kvm/devices/vcpu.rst "KVM_ARM_VCPU_PVTIME_CTRL".
For x86 see Documentation/virt/kvm/x86/msr.rst "MSR_KVM_STEAL_TIME".
8.25 KVM_CAP_S390_DIAG318
-------------------------
:Architectures: s390
This capability enables a guest to set information about its control program
(i.e. guest kernel type and version). The information is helpful during
system/firmware service events, providing additional data about the guest
environments running on the machine.
The information is associated with the DIAGNOSE 0x318 instruction, which sets
an 8-byte value consisting of a one-byte Control Program Name Code (CPNC) and
a 7-byte Control Program Version Code (CPVC). The CPNC determines what
environment the control program is running in (e.g. Linux, z/VM...), and the
CPVC is used for information specific to OS (e.g. Linux version, Linux
distribution...)
If this capability is available, then the CPNC and CPVC can be synchronized
between KVM and userspace via the sync regs mechanism (KVM_SYNC_DIAG318).
8.26 KVM_CAP_X86_USER_SPACE_MSR
-------------------------------
:Architectures: x86
This capability indicates that KVM supports deflection of MSR reads and
writes to user space. It can be enabled on a VM level. If enabled, MSR
accesses that would usually trigger a #GP by KVM into the guest will
instead get bounced to user space through the KVM_EXIT_X86_RDMSR and
KVM_EXIT_X86_WRMSR exit notifications.
8.27 KVM_CAP_X86_MSR_FILTER
---------------------------
:Architectures: x86
This capability indicates that KVM supports that accesses to user defined MSRs
may be rejected. With this capability exposed, KVM exports new VM ioctl
KVM_X86_SET_MSR_FILTER which user space can call to specify bitmaps of MSR
ranges that KVM should deny access to.
In combination with KVM_CAP_X86_USER_SPACE_MSR, this allows user space to
trap and emulate MSRs that are outside of the scope of KVM as well as
limit the attack surface on KVM's MSR emulation code.
8.30 KVM_CAP_XEN_HVM
--------------------
:Architectures: x86
This capability indicates the features that Xen supports for hosting Xen
PVHVM guests. Valid flags are::
#define KVM_XEN_HVM_CONFIG_HYPERCALL_MSR (1 << 0)
#define KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL (1 << 1)
#define KVM_XEN_HVM_CONFIG_SHARED_INFO (1 << 2)
#define KVM_XEN_HVM_CONFIG_RUNSTATE (1 << 3)
#define KVM_XEN_HVM_CONFIG_EVTCHN_2LEVEL (1 << 4)
#define KVM_XEN_HVM_CONFIG_EVTCHN_SEND (1 << 5)
#define KVM_XEN_HVM_CONFIG_RUNSTATE_UPDATE_FLAG (1 << 6)
#define KVM_XEN_HVM_CONFIG_PVCLOCK_TSC_UNSTABLE (1 << 7)
The KVM_XEN_HVM_CONFIG_HYPERCALL_MSR flag indicates that the KVM_XEN_HVM_CONFIG
ioctl is available, for the guest to set its hypercall page.
If KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL is also set, the same flag may also be
provided in the flags to KVM_XEN_HVM_CONFIG, without providing hypercall page
contents, to request that KVM generate hypercall page content automatically
and also enable interception of guest hypercalls with KVM_EXIT_XEN.
The KVM_XEN_HVM_CONFIG_SHARED_INFO flag indicates the availability of the
KVM_XEN_HVM_SET_ATTR, KVM_XEN_HVM_GET_ATTR, KVM_XEN_VCPU_SET_ATTR and
KVM_XEN_VCPU_GET_ATTR ioctls, as well as the delivery of exception vectors
for event channel upcalls when the evtchn_upcall_pending field of a vcpu's
vcpu_info is set.
The KVM_XEN_HVM_CONFIG_RUNSTATE flag indicates that the runstate-related
features KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADDR/_CURRENT/_DATA/_ADJUST are
supported by the KVM_XEN_VCPU_SET_ATTR/KVM_XEN_VCPU_GET_ATTR ioctls.
The KVM_XEN_HVM_CONFIG_EVTCHN_2LEVEL flag indicates that IRQ routing entries
of the type KVM_IRQ_ROUTING_XEN_EVTCHN are supported, with the priority
field set to indicate 2 level event channel delivery.
The KVM_XEN_HVM_CONFIG_EVTCHN_SEND flag indicates that KVM supports
injecting event channel events directly into the guest with the
KVM_XEN_HVM_EVTCHN_SEND ioctl. It also indicates support for the
KVM_XEN_ATTR_TYPE_EVTCHN/XEN_VERSION HVM attributes and the
KVM_XEN_VCPU_ATTR_TYPE_VCPU_ID/TIMER/UPCALL_VECTOR vCPU attributes.
related to event channel delivery, timers, and the XENVER_version
interception.
The KVM_XEN_HVM_CONFIG_RUNSTATE_UPDATE_FLAG flag indicates that KVM supports
the KVM_XEN_ATTR_TYPE_RUNSTATE_UPDATE_FLAG attribute in the KVM_XEN_SET_ATTR
and KVM_XEN_GET_ATTR ioctls. This controls whether KVM will set the
XEN_RUNSTATE_UPDATE flag in guest memory mapped vcpu_runstate_info during
updates of the runstate information. Note that versions of KVM which support
the RUNSTATE feature above, but not the RUNSTATE_UPDATE_FLAG feature, will
always set the XEN_RUNSTATE_UPDATE flag when updating the guest structure,
which is perhaps counterintuitive. When this flag is advertised, KVM will
behave more correctly, not using the XEN_RUNSTATE_UPDATE flag until/unless
specifically enabled (by the guest making the hypercall, causing the VMM
to enable the KVM_XEN_ATTR_TYPE_RUNSTATE_UPDATE_FLAG attribute).
The KVM_XEN_HVM_CONFIG_PVCLOCK_TSC_UNSTABLE flag indicates that KVM supports
clearing the PVCLOCK_TSC_STABLE_BIT flag in Xen pvclock sources. This will be
done when the KVM_CAP_XEN_HVM ioctl sets the
KVM_XEN_HVM_CONFIG_PVCLOCK_TSC_UNSTABLE flag.
8.31 KVM_CAP_SPAPR_MULTITCE
---------------------------
:Architectures: ppc
:Type: vm
This capability means the kernel is capable of handling hypercalls
H_PUT_TCE_INDIRECT and H_STUFF_TCE without passing those into the user
space. This significantly accelerates DMA operations for PPC KVM guests.
User space should expect that its handlers for these hypercalls
are not going to be called if user space previously registered LIOBN
in KVM (via KVM_CREATE_SPAPR_TCE or similar calls).
In order to enable H_PUT_TCE_INDIRECT and H_STUFF_TCE use in the guest,
user space might have to advertise it for the guest. For example,
IBM pSeries (sPAPR) guest starts using them if "hcall-multi-tce" is
present in the "ibm,hypertas-functions" device-tree property.
The hypercalls mentioned above may or may not be processed successfully
in the kernel based fast path. If they can not be handled by the kernel,
they will get passed on to user space. So user space still has to have
an implementation for these despite the in kernel acceleration.
This capability is always enabled.
8.32 KVM_CAP_PTP_KVM
--------------------
:Architectures: arm64
This capability indicates that the KVM virtual PTP service is
supported in the host. A VMM can check whether the service is
available to the guest on migration.
8.37 KVM_CAP_S390_PROTECTED_DUMP
--------------------------------
:Architectures: s390
:Type: vm
This capability indicates that KVM and the Ultravisor support dumping
PV guests. The `KVM_PV_DUMP` command is available for the
`KVM_S390_PV_COMMAND` ioctl and the `KVM_PV_INFO` command provides
dump related UV data. Also the vcpu ioctl `KVM_S390_PV_CPU_COMMAND` is
available and supports the `KVM_PV_DUMP_CPU` subcommand.
8.39 KVM_CAP_S390_CPU_TOPOLOGY
------------------------------
:Architectures: s390
:Type: vm
This capability indicates that KVM will provide the S390 CPU Topology
facility which consist of the interpretation of the PTF instruction for
the function code 2 along with interception and forwarding of both the
PTF instruction with function codes 0 or 1 and the STSI(15,1,x)
instruction to the userland hypervisor.
The stfle facility 11, CPU Topology facility, should not be indicated
to the guest without this capability.
When this capability is present, KVM provides a new attribute group
on vm fd, KVM_S390_VM_CPU_TOPOLOGY.
This new attribute allows to get, set or clear the Modified Change
Topology Report (MTCR) bit of the SCA through the kvm_device_attr
structure.
When getting the Modified Change Topology Report value, the attr->addr
must point to a byte where the value will be stored or retrieved from.
8.41 KVM_CAP_VM_TYPES
---------------------
:Architectures: x86
:Type: system ioctl
This capability returns a bitmap of support VM types. The 1-setting of bit @n
means the VM type with value @n is supported. Possible values of @n are::
#define KVM_X86_DEFAULT_VM 0
#define KVM_X86_SW_PROTECTED_VM 1
#define KVM_X86_SEV_VM 2
#define KVM_X86_SEV_ES_VM 3
Note, KVM_X86_SW_PROTECTED_VM is currently only for development and testing.
Do not use KVM_X86_SW_PROTECTED_VM for "real" VMs, and especially not in
production. The behavior and effective ABI for software-protected VMs is
unstable.
8.42 KVM_CAP_PPC_RPT_INVALIDATE
-------------------------------
:Architectures: ppc
This capability indicates that the kernel is capable of handling
H_RPT_INVALIDATE hcall.
In order to enable the use of H_RPT_INVALIDATE in the guest,
user space might have to advertise it for the guest. For example,
IBM pSeries (sPAPR) guest starts using it if "hcall-rpt-invalidate" is
present in the "ibm,hypertas-functions" device-tree property.
This capability is enabled for hypervisors on platforms like POWER9
that support radix MMU.
8.43 KVM_CAP_PPC_AIL_MODE_3
---------------------------
:Architectures: ppc
This capability indicates that the kernel supports the mode 3 setting for the
"Address Translation Mode on Interrupt" aka "Alternate Interrupt Location"
resource that is controlled with the H_SET_MODE hypercall.
This capability allows a guest kernel to use a better-performance mode for
handling interrupts and system calls.
8.44 KVM_CAP_MEMORY_FAULT_INFO
------------------------------
:Architectures: x86
The presence of this capability indicates that KVM_RUN will fill
kvm_run.memory_fault if KVM cannot resolve a guest page fault VM-Exit, e.g. if
there is a valid memslot but no backing VMA for the corresponding host virtual
address.
The information in kvm_run.memory_fault is valid if and only if KVM_RUN returns
an error with errno=EFAULT or errno=EHWPOISON *and* kvm_run.exit_reason is set
to KVM_EXIT_MEMORY_FAULT.
Note: Userspaces which attempt to resolve memory faults so that they can retry
KVM_RUN are encouraged to guard against repeatedly receiving the same
error/annotated fault.
See KVM_EXIT_MEMORY_FAULT for more information.
8.45 KVM_CAP_X86_GUEST_MODE
---------------------------
:Architectures: x86
The presence of this capability indicates that KVM_RUN will update the
KVM_RUN_X86_GUEST_MODE bit in kvm_run.flags to indicate whether the
vCPU was executing nested guest code when it exited.
KVM exits with the register state of either the L1 or L2 guest
depending on which executed at the time of an exit. Userspace must
take care to differentiate between these cases.
9. 알려진 KVM API 문제
9264-9323KVM API에는 userspace가 주의해야 할 불일치와 흔한 함정이 있으며 대부분 architecture-specific합니다. 현재 이 절은 x86의 supported-CPUID 처리, obsolete capability와 GET/SET ioctl 순서 문제를 기록합니다.
`KVM_GET_SUPPORTED_CPUID`의 결과는 일반적으로 그대로 `KVM_SET_CPUID2`에 전달할 수 있도록 설계됐지만 local APIC 기능과 topology leaf에는 별도 조건이 있습니다.
Feature조건
`CPUID.1:ECX[21]` X2APIC`KVM_CREATE_IRQCHIP` 또는 `KVM_ENABLE_CAP(KVM_CAP_IRQCHIP_SPLIT)`으로 in-kernel local APIC emulation enable
`KVM_FEATURE_PV_UNHALT`X2APIC과 동일하게 in-kernel local APIC 필요
`CPUID.1:ECX[24]` TSC_DEADLINE구형 kernel은 bit를 보고하지 않아도 `KVM_CAP_TSC_DEADLINE_TIMER`와 in-kernel local APIC이 있으면 enable 가능
Supported CPUID bit와 실제 enable 조건을 함께 확인해야 합니다.
새 kernel은 `KVM_GET_SUPPORTED_CPUID`에 TSC_DEADLINE bit를 보고하지만 오래된 kernel에서는 capability와 irqchip 구성으로 지원 여부를 따로 판단해야 합니다.
Host topology를 포함하는 CPUID leaf `0x0b`, `0x1f`, `0x8000001e`는 KVM version마다 반환값이 달라 userspace가 의존해서는 안 됩니다. 현재 구현은 이 정보를 모두 0으로 반환합니다.
Guest topology를 만들려면 세 leaf 값을 vCPU마다 알맞게 달리 설정해야 합니다. APIC ID는 `0x0b`와 `0x1f`의 모든 subleaf에서 EDX, `0x8000001e`에서는 EAX에 있으며 후자의 EBX[7:0]과 ECX[7:0]에는 각각 core ID와 node ID가 들어갑니다.
Obsolete `KVM_CAP_DISABLE_QUIRKS`는 실제로 어떤 quirk를 끌 수 있는지 userspace에 알려주지 않습니다. 가능하면 `KVM_CHECK_EXTENSION(KVM_CAP_DISABLE_QUIRKS2)`로 지원 bitmask를 조회해야 합니다.
`KVM_GET_*`와 `KVM_SET_*` ioctl 사이의 요구 ordering은 이 원문에서도 아직 TBD입니다. 문서가 보장하지 않는 순서를 추정해 자동화하지 말고 각 architecture와 ioctl의 개별 계약을 따라야 합니다.
9. Known KVM API problems
=========================
In some cases, KVM's API has some inconsistencies or common pitfalls
that userspace need to be aware of. This section details some of
these issues.
Most of them are architecture specific, so the section is split by
architecture.
9.1. x86
--------
``KVM_GET_SUPPORTED_CPUID`` issues
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In general, ``KVM_GET_SUPPORTED_CPUID`` is designed so that it is possible
to take its result and pass it directly to ``KVM_SET_CPUID2``. This section
documents some cases in which that requires some care.
Local APIC features
~~~~~~~~~~~~~~~~~~~
CPU[EAX=1]:ECX[21] (X2APIC) is reported by ``KVM_GET_SUPPORTED_CPUID``,
but it can only be enabled if ``KVM_CREATE_IRQCHIP`` or
``KVM_ENABLE_CAP(KVM_CAP_IRQCHIP_SPLIT)`` are used to enable in-kernel emulation of
the local APIC.
The same is true for the ``KVM_FEATURE_PV_UNHALT`` paravirtualized feature.
On older versions of Linux, CPU[EAX=1]:ECX[24] (TSC_DEADLINE) is not reported by
``KVM_GET_SUPPORTED_CPUID``, but it can be enabled if ``KVM_CAP_TSC_DEADLINE_TIMER``
is present and the kernel has enabled in-kernel emulation of the local APIC.
On newer versions, ``KVM_GET_SUPPORTED_CPUID`` does report the bit as available.
CPU topology
~~~~~~~~~~~~
Several CPUID values include topology information for the host CPU:
0x0b and 0x1f for Intel systems, 0x8000001e for AMD systems. Different
versions of KVM return different values for this information and userspace
should not rely on it. Currently they return all zeroes.
If userspace wishes to set up a guest topology, it should be careful that
the values of these three leaves differ for each CPU. In particular,
the APIC ID is found in EDX for all subleaves of 0x0b and 0x1f, and in EAX
for 0x8000001e; the latter also encodes the core id and node id in bits
7:0 of EBX and ECX respectively.
Obsolete ioctls and capabilities
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
KVM_CAP_DISABLE_QUIRKS does not let userspace know which quirks are actually
available. Use ``KVM_CHECK_EXTENSION(KVM_CAP_DISABLE_QUIRKS2)`` instead if
available.
Ordering of KVM_GET_*/KVM_SET_* ioctls
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TBD
요약·해설
api.rst:1-9323이 문서는 KVM system·VM·vCPU·device fd와 ioctl 계약, `kvm_run` exit, memory·register·interrupt 제어, vCPU·VM capability 및 알려진 API 문제를 원문 1~9,323줄에 걸쳐 설명합니다.
Architecture별로 x86, arm64, PowerPC, s390, MIPS, RISC-V의 동작을 구분하고 manual dirty protection, dirty-log ring, SEV·SGX·MTE·protected VM, Hyper-V·Xen interface와 migration state를 함께 다룹니다.
Capability 반환값은 boolean, version, bitmap 또는 enum일 수 있으므로 각 항목의 target과 enable 시점, ioctl ordering, userspace fallback 조건을 그대로 지켜야 합니다. 특히 CPUID topology와 obsolete quirk ioctl처럼 알려진 함정은 마지막 절의 제한을 적용해야 합니다.