| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
=================================================================== |
| 4 |
The Definitive KVM (Kernel-based Virtual Machine) API Documentation |
| 5 |
=================================================================== |
| 6 |
|
| 7 |
1. General description |
| 8 |
====================== |
| 9 |
|
| 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. |
| 18 |
|
| 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: |
| 23 |
|
| 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. |
| 27 |
|
| 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. |
| 31 |
|
| 32 |
VM ioctls must be issued from the same process (address space) that was |
| 33 |
used to create the VM. |
| 34 |
|
| 35 |
- vcpu ioctls: These query and set attributes that control the operation |
| 36 |
of a single virtual cpu. |
| 37 |
|
| 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. |
| 42 |
|
| 43 |
- device ioctls: These query and set attributes that control the operation |
| 44 |
of a single device. |
| 45 |
|
| 46 |
device ioctls must be issued from the same process (address space) that |
| 47 |
was used to create the VM. |
| 48 |
|
| 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. |
| 51 |
|
| 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`). |
| 58 |
|
| 59 |
|
| 60 |
2. Restrictions |
| 61 |
=============== |
| 62 |
|
| 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. |
| 69 |
|
| 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. |
| 78 |
|
| 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. |
| 85 |
|
| 86 |
|
| 87 |
3. Extensions |
| 88 |
============= |
| 89 |
|
| 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. |
| 94 |
|
| 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. |
| 99 |
|
| 100 |
|
| 101 |
4. API description |
| 102 |
================== |
| 103 |
|
| 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: |
| 107 |
|
| 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>`. |
| 114 |
|
| 115 |
Architectures: |
| 116 |
which instruction set architectures provide this ioctl. |
| 117 |
x86 includes both i386 and x86_64. |
| 118 |
|
| 119 |
Type: |
| 120 |
system, vm, or vcpu. |
| 121 |
|
| 122 |
Parameters: |
| 123 |
what parameters are accepted by the ioctl. |
| 124 |
|
| 125 |
Returns: |
| 126 |
the return value. General error numbers (EBADF, ENOMEM, EINVAL) |
| 127 |
are not detailed, but errors with specific meanings are. |
| 128 |
|
| 129 |
|
| 130 |
.. _KVM_GET_API_VERSION: |
| 131 |
|
| 132 |
4.1 KVM_GET_API_VERSION |
| 133 |
----------------------- |
| 134 |
|
| 135 |
:Capability: basic |
| 136 |
:Architectures: all |
| 137 |
:Type: system ioctl |
| 138 |
:Parameters: none |
| 139 |
:Returns: the constant KVM_API_VERSION (=12) |
| 140 |
|
| 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. |
| 147 |
|
| 148 |
|
| 149 |
4.2 KVM_CREATE_VM |
| 150 |
----------------- |
| 151 |
|
| 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. |
| 157 |
|
| 158 |
The new VM has no virtual cpus and no memory. |
| 159 |
You probably want to use 0 as machine type. |
| 160 |
|
| 161 |
X86: |
| 162 |
^^^^ |
| 163 |
|
| 164 |
Supported X86 VM types can be queried via KVM_CAP_VM_TYPES. |
| 165 |
|
| 166 |
S390: |
| 167 |
^^^^^ |
| 168 |
|
| 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). |
| 172 |
|
| 173 |
MIPS: |
| 174 |
^^^^^ |
| 175 |
|
| 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. |
| 180 |
|
| 181 |
ARM64: |
| 182 |
^^^^^^ |
| 183 |
|
| 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. |
| 191 |
|
| 192 |
e.g, to configure a guest to use 48bit physical address size:: |
| 193 |
|
| 194 |
vm_fd = ioctl(dev_fd, KVM_CREATE_VM, KVM_VM_TYPE_ARM_IPA_SIZE(48)); |
| 195 |
|
| 196 |
The requested size (IPA_Bits) must be: |
| 197 |
|
| 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 |
== ========================================================= |
| 203 |
|
| 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. |
| 208 |
|
| 209 |
Creation of the VM will fail if the requested IPA size (whether it is |
| 210 |
implicit or explicit) is unsupported on the host. |
| 211 |
|
| 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). |
| 216 |
|
| 217 |
|
| 218 |
4.3 KVM_GET_MSR_INDEX_LIST, KVM_GET_MSR_FEATURE_INDEX_LIST |
| 219 |
---------------------------------------------------------- |
| 220 |
|
| 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 |
| 226 |
|
| 227 |
Errors: |
| 228 |
|
| 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 |
====== ============================================================ |
| 234 |
|
| 235 |
:: |
| 236 |
|
| 237 |
struct kvm_msr_list { |
| 238 |
__u32 nmsrs; /* number of msrs in entries */ |
| 239 |
__u32 indices[0]; |
| 240 |
}; |
| 241 |
|
| 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. |
| 245 |
|
| 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. |
| 248 |
|
| 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. |
| 252 |
|
| 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. |
| 258 |
|
| 259 |
|
| 260 |
.. _KVM_CHECK_EXTENSION: |
| 261 |
|
| 262 |
4.4 KVM_CHECK_EXTENSION |
| 263 |
----------------------- |
| 264 |
|
| 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 |
| 270 |
|
| 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. |
| 276 |
|
| 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) |
| 280 |
|
| 281 |
4.5 KVM_GET_VCPU_MMAP_SIZE |
| 282 |
-------------------------- |
| 283 |
|
| 284 |
:Capability: basic |
| 285 |
:Architectures: all |
| 286 |
:Type: system ioctl |
| 287 |
:Parameters: none |
| 288 |
:Returns: size of vcpu mmap area, in bytes |
| 289 |
|
| 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. |
| 293 |
|
| 294 |
Besides the size of the KVM_RUN communication region, other areas of |
| 295 |
the VCPU file descriptor can be mmap-ed, including: |
| 296 |
|
| 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. |
| 301 |
|
| 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`. |
| 305 |
|
| 306 |
|
| 307 |
4.7 KVM_CREATE_VCPU |
| 308 |
------------------- |
| 309 |
|
| 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 |
| 315 |
|
| 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). |
| 318 |
|
| 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. |
| 323 |
|
| 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. |
| 328 |
|
| 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. |
| 331 |
|
| 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. |
| 334 |
|
| 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. |
| 347 |
|
| 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. |
| 352 |
|
| 353 |
|
| 354 |
4.8 KVM_GET_DIRTY_LOG |
| 355 |
--------------------- |
| 356 |
|
| 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 |
| 362 |
|
| 363 |
:: |
| 364 |
|
| 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 |
}; |
| 374 |
|
| 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. |
| 379 |
|
| 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. |
| 383 |
|
| 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. |
| 387 |
|
| 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. |
| 390 |
|
| 391 |
|
| 392 |
4.10 KVM_RUN |
| 393 |
------------ |
| 394 |
|
| 395 |
:Capability: basic |
| 396 |
:Architectures: all |
| 397 |
:Type: vcpu ioctl |
| 398 |
:Parameters: none |
| 399 |
:Returns: 0 on success, -1 on error |
| 400 |
|
| 401 |
Errors: |
| 402 |
|
| 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 |
======= ============================================================== |
| 411 |
|
| 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). |
| 417 |
|
| 418 |
|
| 419 |
4.11 KVM_GET_REGS |
| 420 |
----------------- |
| 421 |
|
| 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 |
| 427 |
|
| 428 |
Reads the general purpose registers from the vcpu. |
| 429 |
|
| 430 |
:: |
| 431 |
|
| 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 |
}; |
| 441 |
|
| 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 |
}; |
| 450 |
|
| 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 |
}; |
| 457 |
|
| 458 |
|
| 459 |
4.12 KVM_SET_REGS |
| 460 |
----------------- |
| 461 |
|
| 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 |
| 467 |
|
| 468 |
Writes the general purpose registers into the vcpu. |
| 469 |
|
| 470 |
See KVM_GET_REGS for the data structure. |
| 471 |
|
| 472 |
|
| 473 |
4.13 KVM_GET_SREGS |
| 474 |
------------------ |
| 475 |
|
| 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 |
| 481 |
|
| 482 |
Reads special registers from the vcpu. |
| 483 |
|
| 484 |
:: |
| 485 |
|
| 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 |
}; |
| 496 |
|
| 497 |
/* ppc -- see arch/powerpc/include/uapi/asm/kvm.h */ |
| 498 |
|
| 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. |
| 502 |
|
| 503 |
|
| 504 |
4.14 KVM_SET_SREGS |
| 505 |
------------------ |
| 506 |
|
| 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 |
| 512 |
|
| 513 |
Writes special registers into the vcpu. See KVM_GET_SREGS for the |
| 514 |
data structures. |
| 515 |
|
| 516 |
|
| 517 |
4.15 KVM_TRANSLATE |
| 518 |
------------------ |
| 519 |
|
| 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 |
| 525 |
|
| 526 |
Translates a virtual address according to the vcpu's current address |
| 527 |
translation mode. |
| 528 |
|
| 529 |
:: |
| 530 |
|
| 531 |
struct kvm_translation { |
| 532 |
/* in */ |
| 533 |
__u64 linear_address; |
| 534 |
|
| 535 |
/* out */ |
| 536 |
__u64 physical_address; |
| 537 |
__u8 valid; |
| 538 |
__u8 writeable; |
| 539 |
__u8 usermode; |
| 540 |
__u8 pad[5]; |
| 541 |
}; |
| 542 |
|
| 543 |
|
| 544 |
4.16 KVM_INTERRUPT |
| 545 |
------------------ |
| 546 |
|
| 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. |
| 552 |
|
| 553 |
Queues a hardware interrupt vector to be injected. |
| 554 |
|
| 555 |
:: |
| 556 |
|
| 557 |
/* for KVM_INTERRUPT */ |
| 558 |
struct kvm_interrupt { |
| 559 |
/* in */ |
| 560 |
__u32 irq; |
| 561 |
}; |
| 562 |
|
| 563 |
X86: |
| 564 |
^^^^ |
| 565 |
|
| 566 |
:Returns: |
| 567 |
|
| 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 |
========= =================================== |
| 575 |
|
| 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. |
| 578 |
|
| 579 |
PPC: |
| 580 |
^^^^ |
| 581 |
|
| 582 |
Queues an external interrupt to be injected. This ioctl is overloaded |
| 583 |
with 3 different irq values: |
| 584 |
|
| 585 |
a) KVM_INTERRUPT_SET |
| 586 |
|
| 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. |
| 589 |
|
| 590 |
b) KVM_INTERRUPT_UNSET |
| 591 |
|
| 592 |
This unsets any pending interrupt. |
| 593 |
|
| 594 |
Only available with KVM_CAP_PPC_UNSET_IRQ. |
| 595 |
|
| 596 |
c) KVM_INTERRUPT_SET_LEVEL |
| 597 |
|
| 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. |
| 601 |
|
| 602 |
Only available with KVM_CAP_PPC_IRQ_LEVEL. |
| 603 |
|
| 604 |
Note that any value for 'irq' other than the ones stated above is invalid |
| 605 |
and incurs unexpected behavior. |
| 606 |
|
| 607 |
This is an asynchronous vcpu ioctl and can be invoked from any thread. |
| 608 |
|
| 609 |
MIPS: |
| 610 |
^^^^^ |
| 611 |
|
| 612 |
Queues an external interrupt to be injected into the virtual CPU. A negative |
| 613 |
interrupt number dequeues the interrupt. |
| 614 |
|
| 615 |
This is an asynchronous vcpu ioctl and can be invoked from any thread. |
| 616 |
|
| 617 |
RISC-V: |
| 618 |
^^^^^^^ |
| 619 |
|
| 620 |
Queues an external interrupt to be injected into the virtual CPU. This ioctl |
| 621 |
is overloaded with 2 different irq values: |
| 622 |
|
| 623 |
a) KVM_INTERRUPT_SET |
| 624 |
|
| 625 |
This sets external interrupt for a virtual CPU and it will receive |
| 626 |
once it is ready. |
| 627 |
|
| 628 |
b) KVM_INTERRUPT_UNSET |
| 629 |
|
| 630 |
This clears pending external interrupt for a virtual CPU. |
| 631 |
|
| 632 |
This is an asynchronous vcpu ioctl and can be invoked from any thread. |
| 633 |
|
| 634 |
LOONGARCH: |
| 635 |
^^^^^^^^^^ |
| 636 |
|
| 637 |
Queues an external interrupt to be injected into the virtual CPU. A negative |
| 638 |
interrupt number dequeues the interrupt. |
| 639 |
|
| 640 |
This is an asynchronous vcpu ioctl and can be invoked from any thread. |
| 641 |
|
| 642 |
|
| 643 |
4.18 KVM_GET_MSRS |
| 644 |
----------------- |
| 645 |
|
| 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 |
| 652 |
|
| 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. |
| 658 |
|
| 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. |
| 662 |
|
| 663 |
:: |
| 664 |
|
| 665 |
struct kvm_msrs { |
| 666 |
__u32 nmsrs; /* number of msrs in entries */ |
| 667 |
__u32 pad; |
| 668 |
|
| 669 |
struct kvm_msr_entry entries[0]; |
| 670 |
}; |
| 671 |
|
| 672 |
struct kvm_msr_entry { |
| 673 |
__u32 index; |
| 674 |
__u32 reserved; |
| 675 |
__u64 data; |
| 676 |
}; |
| 677 |
|
| 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. |
| 681 |
|
| 682 |
|
| 683 |
4.19 KVM_SET_MSRS |
| 684 |
----------------- |
| 685 |
|
| 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 |
| 691 |
|
| 692 |
Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the |
| 693 |
data structures. |
| 694 |
|
| 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. |
| 698 |
|
| 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. |
| 703 |
|
| 704 |
|
| 705 |
4.20 KVM_SET_CPUID |
| 706 |
------------------ |
| 707 |
|
| 708 |
:Capability: basic |
| 709 |
:Architectures: x86 |
| 710 |
:Type: vcpu ioctl |
| 711 |
:Parameters: struct kvm_cpuid (in) |
| 712 |
:Returns: 0 on success, -1 on error |
| 713 |
|
| 714 |
Defines the vcpu responses to the cpuid instruction. Applications |
| 715 |
should use the KVM_SET_CPUID2 ioctl if available. |
| 716 |
|
| 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. |
| 725 |
|
| 726 |
:: |
| 727 |
|
| 728 |
struct kvm_cpuid_entry { |
| 729 |
__u32 function; |
| 730 |
__u32 eax; |
| 731 |
__u32 ebx; |
| 732 |
__u32 ecx; |
| 733 |
__u32 edx; |
| 734 |
__u32 padding; |
| 735 |
}; |
| 736 |
|
| 737 |
/* for KVM_SET_CPUID */ |
| 738 |
struct kvm_cpuid { |
| 739 |
__u32 nent; |
| 740 |
__u32 padding; |
| 741 |
struct kvm_cpuid_entry entries[0]; |
| 742 |
}; |
| 743 |
|
| 744 |
|
| 745 |
4.21 KVM_SET_SIGNAL_MASK |
| 746 |
------------------------ |
| 747 |
|
| 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 |
| 753 |
|
| 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. |
| 758 |
|
| 759 |
Note the signal will only be delivered if not blocked by the original |
| 760 |
signal mask. |
| 761 |
|
| 762 |
:: |
| 763 |
|
| 764 |
/* for KVM_SET_SIGNAL_MASK */ |
| 765 |
struct kvm_signal_mask { |
| 766 |
__u32 len; |
| 767 |
__u8 sigset[0]; |
| 768 |
}; |
| 769 |
|
| 770 |
|
| 771 |
4.22 KVM_GET_FPU |
| 772 |
---------------- |
| 773 |
|
| 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 |
| 779 |
|
| 780 |
Reads the floating point state from the vcpu. |
| 781 |
|
| 782 |
:: |
| 783 |
|
| 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 |
}; |
| 798 |
|
| 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 |
}; |
| 807 |
|
| 808 |
|
| 809 |
4.23 KVM_SET_FPU |
| 810 |
---------------- |
| 811 |
|
| 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 |
| 817 |
|
| 818 |
Writes the floating point state to the vcpu. |
| 819 |
|
| 820 |
:: |
| 821 |
|
| 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 |
}; |
| 836 |
|
| 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 |
}; |
| 845 |
|
| 846 |
|
| 847 |
4.24 KVM_CREATE_IRQCHIP |
| 848 |
----------------------- |
| 849 |
|
| 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 |
| 855 |
|
| 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. |
| 864 |
|
| 865 |
Note that on s390 the KVM_CAP_S390_IRQCHIP vm capability needs to be enabled |
| 866 |
before KVM_CREATE_IRQCHIP can be used. |
| 867 |
|
| 868 |
|
| 869 |
4.25 KVM_IRQ_LINE |
| 870 |
----------------- |
| 871 |
|
| 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 |
| 877 |
|
| 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. |
| 882 |
|
| 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). |
| 886 |
|
| 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). |
| 895 |
|
| 896 |
|
| 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:: |
| 901 |
|
| 902 |
bits: | 31 ... 28 | 27 ... 24 | 23 ... 16 | 15 ... 0 | |
| 903 |
field: | vcpu2_index | irq_type | vcpu_index | irq_id | |
| 904 |
|
| 905 |
The irq_type field has the following values: |
| 906 |
|
| 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.) |
| 914 |
|
| 915 |
(The irq_id field thus corresponds nicely to the IRQ ID in the ARM GIC specs) |
| 916 |
|
| 917 |
In both cases, level is used to assert/deassert the line. |
| 918 |
|
| 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. |
| 922 |
|
| 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. |
| 926 |
|
| 927 |
:: |
| 928 |
|
| 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 |
}; |
| 936 |
|
| 937 |
|
| 938 |
4.26 KVM_GET_IRQCHIP |
| 939 |
-------------------- |
| 940 |
|
| 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 |
| 946 |
|
| 947 |
Reads the state of a kernel interrupt controller created with |
| 948 |
KVM_CREATE_IRQCHIP into a buffer provided by the caller. |
| 949 |
|
| 950 |
:: |
| 951 |
|
| 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 |
}; |
| 961 |
|
| 962 |
|
| 963 |
4.27 KVM_SET_IRQCHIP |
| 964 |
-------------------- |
| 965 |
|
| 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 |
| 971 |
|
| 972 |
Sets the state of a kernel interrupt controller created with |
| 973 |
KVM_CREATE_IRQCHIP from a buffer provided by the caller. |
| 974 |
|
| 975 |
:: |
| 976 |
|
| 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 |
}; |
| 986 |
|
| 987 |
|
| 988 |
4.28 KVM_XEN_HVM_CONFIG |
| 989 |
----------------------- |
| 990 |
|
| 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 |
| 996 |
|
| 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. |
| 1002 |
|
| 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. |
| 1006 |
|
| 1007 |
:: |
| 1008 |
|
| 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 |
}; |
| 1018 |
|
| 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: |
| 1021 |
|
| 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. |
| 1026 |
|
| 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 |
| 1035 |
|
| 1036 |
No other flags are currently valid in the struct kvm_xen_hvm_config. |
| 1037 |
|
| 1038 |
4.29 KVM_GET_CLOCK |
| 1039 |
------------------ |
| 1040 |
|
| 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 |
| 1046 |
|
| 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. |
| 1050 |
|
| 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. |
| 1053 |
|
| 1054 |
The following flags are defined: |
| 1055 |
|
| 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. |
| 1063 |
|
| 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. |
| 1069 |
|
| 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. |
| 1075 |
|
| 1076 |
:: |
| 1077 |
|
| 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 |
}; |
| 1086 |
|
| 1087 |
|
| 1088 |
4.30 KVM_SET_CLOCK |
| 1089 |
------------------ |
| 1090 |
|
| 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 |
| 1096 |
|
| 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. |
| 1100 |
|
| 1101 |
The following flags can be passed: |
| 1102 |
|
| 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. |
| 1108 |
|
| 1109 |
Other flags returned by ``KVM_GET_CLOCK`` are accepted but ignored. |
| 1110 |
|
| 1111 |
:: |
| 1112 |
|
| 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 |
}; |
| 1121 |
|
| 1122 |
|
| 1123 |
4.31 KVM_GET_VCPU_EVENTS |
| 1124 |
------------------------ |
| 1125 |
|
| 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 |
| 1132 |
|
| 1133 |
X86: |
| 1134 |
^^^^ |
| 1135 |
|
| 1136 |
Gets currently pending exceptions, interrupts, and NMIs as well as related |
| 1137 |
states of the vcpu. |
| 1138 |
|
| 1139 |
:: |
| 1140 |
|
| 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 |
}; |
| 1173 |
|
| 1174 |
The following bits are defined in the flags field: |
| 1175 |
|
| 1176 |
- KVM_VCPUEVENT_VALID_SHADOW may be set to signal that |
| 1177 |
interrupt.shadow contains a valid state. |
| 1178 |
|
| 1179 |
- KVM_VCPUEVENT_VALID_SMM may be set to signal that smi contains a |
| 1180 |
valid state. |
| 1181 |
|
| 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. |
| 1186 |
|
| 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. |
| 1190 |
|
| 1191 |
ARM64: |
| 1192 |
^^^^^^ |
| 1193 |
|
| 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. |
| 1198 |
|
| 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. |
| 1202 |
|
| 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. |
| 1208 |
|
| 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"). |
| 1215 |
|
| 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. |
| 1223 |
|
| 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. |
| 1227 |
|
| 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). |
| 1231 |
|
| 1232 |
Calling this ioctl on a vCPU that hasn't been initialized will return |
| 1233 |
-ENOEXEC. |
| 1234 |
|
| 1235 |
:: |
| 1236 |
|
| 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 |
}; |
| 1248 |
|
| 1249 |
4.32 KVM_SET_VCPU_EVENTS |
| 1250 |
------------------------ |
| 1251 |
|
| 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 |
| 1258 |
|
| 1259 |
X86: |
| 1260 |
^^^^ |
| 1261 |
|
| 1262 |
Set pending exceptions, interrupts, and NMIs as well as related states of the |
| 1263 |
vcpu. |
| 1264 |
|
| 1265 |
See KVM_GET_VCPU_EVENTS for the data structure. |
| 1266 |
|
| 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: |
| 1271 |
|
| 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 |
=============================== ================================== |
| 1277 |
|
| 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. |
| 1281 |
|
| 1282 |
KVM_VCPUEVENT_VALID_SMM can only be set if KVM_CAP_X86_SMM is available. |
| 1283 |
|
| 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. |
| 1288 |
|
| 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. |
| 1292 |
|
| 1293 |
ARM64: |
| 1294 |
^^^^^^ |
| 1295 |
|
| 1296 |
User space may need to inject several types of events to the guest. |
| 1297 |
|
| 1298 |
Set the pending SError exception state for this VCPU. It is not possible to |
| 1299 |
'cancel' an Serror that has been made pending. |
| 1300 |
|
| 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, |
| 1307 |
KVM_EXIT_ARM_NISV, or KVM_EXIT_ARM_LDST64B. This feature is only available if |
| 1308 |
the system supports KVM_CAP_ARM_INJECT_EXT_DABT. This is a helper which |
| 1309 |
provides commonality in how userspace reports accesses for the above cases to |
| 1310 |
guests, across different userspace implementations. Nevertheless, userspace |
| 1311 |
can still emulate all Arm exceptions by manipulating individual registers |
| 1312 |
using the KVM_SET_ONE_REG API. |
| 1313 |
|
| 1314 |
See KVM_GET_VCPU_EVENTS for the data structure. |
| 1315 |
|
| 1316 |
Calling this ioctl on a vCPU that hasn't been initialized will return |
| 1317 |
-ENOEXEC. |
| 1318 |
|
| 1319 |
4.33 KVM_GET_DEBUGREGS |
| 1320 |
---------------------- |
| 1321 |
|
| 1322 |
:Capability: KVM_CAP_DEBUGREGS |
| 1323 |
:Architectures: x86 |
| 1324 |
:Type: vcpu ioctl |
| 1325 |
:Parameters: struct kvm_debugregs (out) |
| 1326 |
:Returns: 0 on success, -1 on error |
| 1327 |
|
| 1328 |
Reads debug registers from the vcpu. |
| 1329 |
|
| 1330 |
:: |
| 1331 |
|
| 1332 |
struct kvm_debugregs { |
| 1333 |
__u64 db[4]; |
| 1334 |
__u64 dr6; |
| 1335 |
__u64 dr7; |
| 1336 |
__u64 flags; |
| 1337 |
__u64 reserved[9]; |
| 1338 |
}; |
| 1339 |
|
| 1340 |
|
| 1341 |
4.34 KVM_SET_DEBUGREGS |
| 1342 |
---------------------- |
| 1343 |
|
| 1344 |
:Capability: KVM_CAP_DEBUGREGS |
| 1345 |
:Architectures: x86 |
| 1346 |
:Type: vcpu ioctl |
| 1347 |
:Parameters: struct kvm_debugregs (in) |
| 1348 |
:Returns: 0 on success, -1 on error |
| 1349 |
|
| 1350 |
Writes debug registers into the vcpu. |
| 1351 |
|
| 1352 |
See KVM_GET_DEBUGREGS for the data structure. The flags field is unused |
| 1353 |
yet and must be cleared on entry. |
| 1354 |
|
| 1355 |
|
| 1356 |
4.35 KVM_SET_USER_MEMORY_REGION |
| 1357 |
------------------------------- |
| 1358 |
|
| 1359 |
:Capability: KVM_CAP_USER_MEMORY |
| 1360 |
:Architectures: all |
| 1361 |
:Type: vm ioctl |
| 1362 |
:Parameters: struct kvm_userspace_memory_region (in) |
| 1363 |
:Returns: 0 on success, -1 on error |
| 1364 |
|
| 1365 |
:: |
| 1366 |
|
| 1367 |
struct kvm_userspace_memory_region { |
| 1368 |
__u32 slot; |
| 1369 |
__u32 flags; |
| 1370 |
__u64 guest_phys_addr; |
| 1371 |
__u64 memory_size; /* bytes */ |
| 1372 |
__u64 userspace_addr; /* start of the userspace allocated memory */ |
| 1373 |
}; |
| 1374 |
|
| 1375 |
/* for kvm_userspace_memory_region::flags */ |
| 1376 |
#define KVM_MEM_LOG_DIRTY_PAGES (1UL << 0) |
| 1377 |
#define KVM_MEM_READONLY (1UL << 1) |
| 1378 |
|
| 1379 |
This ioctl allows the user to create, modify or delete a guest physical |
| 1380 |
memory slot. Bits 0-15 of "slot" specify the slot id and this value |
| 1381 |
should be less than the maximum number of user memory slots supported per |
| 1382 |
VM. The maximum allowed slots can be queried using KVM_CAP_NR_MEMSLOTS. |
| 1383 |
Slots may not overlap in guest physical address space. |
| 1384 |
|
| 1385 |
If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 of "slot" |
| 1386 |
specifies the address space which is being modified. They must be |
| 1387 |
less than the value that KVM_CHECK_EXTENSION returns for the |
| 1388 |
KVM_CAP_MULTI_ADDRESS_SPACE capability. Slots in separate address spaces |
| 1389 |
are unrelated; the restriction on overlapping slots only applies within |
| 1390 |
each address space. |
| 1391 |
|
| 1392 |
Deleting a slot is done by passing zero for memory_size. When changing |
| 1393 |
an existing slot, it may be moved in the guest physical memory space, |
| 1394 |
or its flags may be modified, but it may not be resized. |
| 1395 |
|
| 1396 |
Memory for the region is taken starting at the address denoted by the |
| 1397 |
field userspace_addr, which must point at user addressable memory for |
| 1398 |
the entire memory slot size. Any object may back this memory, including |
| 1399 |
anonymous memory, ordinary files, and hugetlbfs. Changes in the backing |
| 1400 |
of the memory region are automatically reflected into the guest. |
| 1401 |
For example, an mmap() that affects the region will be made visible |
| 1402 |
immediately. Another example is madvise(MADV_DROP). |
| 1403 |
|
| 1404 |
On architectures that support a form of address tagging, userspace_addr must |
| 1405 |
be an untagged address. |
| 1406 |
|
| 1407 |
It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr |
| 1408 |
be identical. This allows large pages in the guest to be backed by large |
| 1409 |
pages in the host. |
| 1410 |
|
| 1411 |
The flags field supports two flags: KVM_MEM_LOG_DIRTY_PAGES and |
| 1412 |
KVM_MEM_READONLY. The former can be set to instruct KVM to keep track of |
| 1413 |
writes to memory within the slot. See KVM_GET_DIRTY_LOG ioctl to know how to |
| 1414 |
use it. The latter can be set, if KVM_CAP_READONLY_MEM capability allows it, |
| 1415 |
to make a new slot read-only. In this case, writes to this memory will be |
| 1416 |
posted to userspace as KVM_EXIT_MMIO exits. |
| 1417 |
|
| 1418 |
For TDX guest, deleting/moving memory region loses guest memory contents. |
| 1419 |
Read only region isn't supported. Only as-id 0 is supported. |
| 1420 |
|
| 1421 |
Note: On arm64, a write generated by the page-table walker (to update |
| 1422 |
the Access and Dirty flags, for example) never results in a |
| 1423 |
KVM_EXIT_MMIO exit when the slot has the KVM_MEM_READONLY flag. This |
| 1424 |
is because KVM cannot provide the data that would be written by the |
| 1425 |
page-table walker, making it impossible to emulate the access. |
| 1426 |
Instead, an abort (data abort if the cause of the page-table update |
| 1427 |
was a load or a store, instruction abort if it was an instruction |
| 1428 |
fetch) is injected in the guest. |
| 1429 |
|
| 1430 |
S390: |
| 1431 |
^^^^^ |
| 1432 |
|
| 1433 |
Returns -EINVAL or -EEXIST if the VM has the KVM_VM_S390_UCONTROL flag set. |
| 1434 |
Returns -EINVAL if called on a protected VM. |
| 1435 |
|
| 1436 |
4.36 KVM_SET_TSS_ADDR |
| 1437 |
--------------------- |
| 1438 |
|
| 1439 |
:Capability: KVM_CAP_SET_TSS_ADDR |
| 1440 |
:Architectures: x86 |
| 1441 |
:Type: vm ioctl |
| 1442 |
:Parameters: unsigned long tss_address (in) |
| 1443 |
:Returns: 0 on success, -1 on error |
| 1444 |
|
| 1445 |
This ioctl defines the physical address of a three-page region in the guest |
| 1446 |
physical address space. The region must be within the first 4GB of the |
| 1447 |
guest physical address space and must not conflict with any memory slot |
| 1448 |
or any mmio address. The guest may malfunction if it accesses this memory |
| 1449 |
region. |
| 1450 |
|
| 1451 |
This ioctl is required on Intel-based hosts. This is needed on Intel hardware |
| 1452 |
because of a quirk in the virtualization implementation (see the internals |
| 1453 |
documentation when it pops into existence). |
| 1454 |
|
| 1455 |
|
| 1456 |
.. _KVM_ENABLE_CAP: |
| 1457 |
|
| 1458 |
4.37 KVM_ENABLE_CAP |
| 1459 |
------------------- |
| 1460 |
|
| 1461 |
:Capability: KVM_CAP_ENABLE_CAP |
| 1462 |
:Architectures: mips, ppc, s390, x86, loongarch |
| 1463 |
:Type: vcpu ioctl |
| 1464 |
:Parameters: struct kvm_enable_cap (in) |
| 1465 |
:Returns: 0 on success; -1 on error |
| 1466 |
|
| 1467 |
:Capability: KVM_CAP_ENABLE_CAP_VM |
| 1468 |
:Architectures: all |
| 1469 |
:Type: vm ioctl |
| 1470 |
:Parameters: struct kvm_enable_cap (in) |
| 1471 |
:Returns: 0 on success; -1 on error |
| 1472 |
|
| 1473 |
.. note:: |
| 1474 |
|
| 1475 |
Not all extensions are enabled by default. Using this ioctl the application |
| 1476 |
can enable an extension, making it available to the guest. |
| 1477 |
|
| 1478 |
On systems that do not support this ioctl, it always fails. On systems that |
| 1479 |
do support it, it only works for extensions that are supported for enablement. |
| 1480 |
|
| 1481 |
To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should |
| 1482 |
be used. |
| 1483 |
|
| 1484 |
:: |
| 1485 |
|
| 1486 |
struct kvm_enable_cap { |
| 1487 |
/* in */ |
| 1488 |
__u32 cap; |
| 1489 |
|
| 1490 |
The capability that is supposed to get enabled. |
| 1491 |
|
| 1492 |
:: |
| 1493 |
|
| 1494 |
__u32 flags; |
| 1495 |
|
| 1496 |
A bitfield indicating future enhancements. Has to be 0 for now. |
| 1497 |
|
| 1498 |
:: |
| 1499 |
|
| 1500 |
__u64 args[4]; |
| 1501 |
|
| 1502 |
Arguments for enabling a feature. If a feature needs initial values to |
| 1503 |
function properly, this is the place to put them. |
| 1504 |
|
| 1505 |
:: |
| 1506 |
|
| 1507 |
__u8 pad[64]; |
| 1508 |
}; |
| 1509 |
|
| 1510 |
The vcpu ioctl should be used for vcpu-specific capabilities, the vm ioctl |
| 1511 |
for vm-wide capabilities. |
| 1512 |
|
| 1513 |
4.38 KVM_GET_MP_STATE |
| 1514 |
--------------------- |
| 1515 |
|
| 1516 |
:Capability: KVM_CAP_MP_STATE |
| 1517 |
:Architectures: x86, s390, arm64, riscv, loongarch |
| 1518 |
:Type: vcpu ioctl |
| 1519 |
:Parameters: struct kvm_mp_state (out) |
| 1520 |
:Returns: 0 on success; -1 on error |
| 1521 |
|
| 1522 |
:: |
| 1523 |
|
| 1524 |
struct kvm_mp_state { |
| 1525 |
__u32 mp_state; |
| 1526 |
}; |
| 1527 |
|
| 1528 |
Returns the vcpu's current "multiprocessing state" (though also valid on |
| 1529 |
uniprocessor guests). |
| 1530 |
|
| 1531 |
Possible values are: |
| 1532 |
|
| 1533 |
========================== =============================================== |
| 1534 |
KVM_MP_STATE_RUNNABLE the vcpu is currently running |
| 1535 |
[x86,arm64,riscv,loongarch] |
| 1536 |
KVM_MP_STATE_UNINITIALIZED the vcpu is an application processor (AP) |
| 1537 |
which has not yet received an INIT signal [x86] |
| 1538 |
KVM_MP_STATE_INIT_RECEIVED the vcpu has received an INIT signal, and is |
| 1539 |
now ready for a SIPI [x86] |
| 1540 |
KVM_MP_STATE_HALTED the vcpu has executed a HLT instruction and |
| 1541 |
is waiting for an interrupt [x86] |
| 1542 |
KVM_MP_STATE_SIPI_RECEIVED the vcpu has just received a SIPI (vector |
| 1543 |
accessible via KVM_GET_VCPU_EVENTS) [x86] |
| 1544 |
KVM_MP_STATE_STOPPED the vcpu is stopped [s390,arm64,riscv] |
| 1545 |
KVM_MP_STATE_CHECK_STOP the vcpu is in a special error state [s390] |
| 1546 |
KVM_MP_STATE_OPERATING the vcpu is operating (running or halted) |
| 1547 |
[s390] |
| 1548 |
KVM_MP_STATE_LOAD the vcpu is in a special load/startup state |
| 1549 |
[s390] |
| 1550 |
KVM_MP_STATE_SUSPENDED the vcpu is in a suspend state and is waiting |
| 1551 |
for a wakeup event [arm64] |
| 1552 |
========================== =============================================== |
| 1553 |
|
| 1554 |
On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an |
| 1555 |
in-kernel irqchip, the multiprocessing state must be maintained by userspace on |
| 1556 |
these architectures. |
| 1557 |
|
| 1558 |
For arm64: |
| 1559 |
^^^^^^^^^^ |
| 1560 |
|
| 1561 |
If a vCPU is in the KVM_MP_STATE_SUSPENDED state, KVM will emulate the |
| 1562 |
architectural execution of a WFI instruction. |
| 1563 |
|
| 1564 |
If a wakeup event is recognized, KVM will exit to userspace with a |
| 1565 |
KVM_SYSTEM_EVENT exit, where the event type is KVM_SYSTEM_EVENT_WAKEUP. If |
| 1566 |
userspace wants to honor the wakeup, it must set the vCPU's MP state to |
| 1567 |
KVM_MP_STATE_RUNNABLE. If it does not, KVM will continue to await a wakeup |
| 1568 |
event in subsequent calls to KVM_RUN. |
| 1569 |
|
| 1570 |
.. warning:: |
| 1571 |
|
| 1572 |
If userspace intends to keep the vCPU in a SUSPENDED state, it is |
| 1573 |
strongly recommended that userspace take action to suppress the |
| 1574 |
wakeup event (such as masking an interrupt). Otherwise, subsequent |
| 1575 |
calls to KVM_RUN will immediately exit with a KVM_SYSTEM_EVENT_WAKEUP |
| 1576 |
event and inadvertently waste CPU cycles. |
| 1577 |
|
| 1578 |
Additionally, if userspace takes action to suppress a wakeup event, |
| 1579 |
it is strongly recommended that it also restores the vCPU to its |
| 1580 |
original state when the vCPU is made RUNNABLE again. For example, |
| 1581 |
if userspace masked a pending interrupt to suppress the wakeup, |
| 1582 |
the interrupt should be unmasked before returning control to the |
| 1583 |
guest. |
| 1584 |
|
| 1585 |
For riscv: |
| 1586 |
^^^^^^^^^^ |
| 1587 |
|
| 1588 |
The only states that are valid are KVM_MP_STATE_STOPPED and |
| 1589 |
KVM_MP_STATE_RUNNABLE which reflect if the vcpu is paused or not. |
| 1590 |
|
| 1591 |
On LoongArch, only the KVM_MP_STATE_RUNNABLE state is used to reflect |
| 1592 |
whether the vcpu is runnable. |
| 1593 |
|
| 1594 |
4.39 KVM_SET_MP_STATE |
| 1595 |
--------------------- |
| 1596 |
|
| 1597 |
:Capability: KVM_CAP_MP_STATE |
| 1598 |
:Architectures: x86, s390, arm64, riscv, loongarch |
| 1599 |
:Type: vcpu ioctl |
| 1600 |
:Parameters: struct kvm_mp_state (in) |
| 1601 |
:Returns: 0 on success; -1 on error |
| 1602 |
|
| 1603 |
Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for |
| 1604 |
arguments. |
| 1605 |
|
| 1606 |
On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an |
| 1607 |
in-kernel irqchip, the multiprocessing state must be maintained by userspace on |
| 1608 |
these architectures. |
| 1609 |
|
| 1610 |
For arm64/riscv: |
| 1611 |
^^^^^^^^^^^^^^^^ |
| 1612 |
|
| 1613 |
The only states that are valid are KVM_MP_STATE_STOPPED and |
| 1614 |
KVM_MP_STATE_RUNNABLE which reflect if the vcpu should be paused or not. |
| 1615 |
|
| 1616 |
On LoongArch, only the KVM_MP_STATE_RUNNABLE state is used to reflect |
| 1617 |
whether the vcpu is runnable. |
| 1618 |
|
| 1619 |
4.40 KVM_SET_IDENTITY_MAP_ADDR |
| 1620 |
------------------------------ |
| 1621 |
|
| 1622 |
:Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR |
| 1623 |
:Architectures: x86 |
| 1624 |
:Type: vm ioctl |
| 1625 |
:Parameters: unsigned long identity (in) |
| 1626 |
:Returns: 0 on success, -1 on error |
| 1627 |
|
| 1628 |
This ioctl defines the physical address of a one-page region in the guest |
| 1629 |
physical address space. The region must be within the first 4GB of the |
| 1630 |
guest physical address space and must not conflict with any memory slot |
| 1631 |
or any mmio address. The guest may malfunction if it accesses this memory |
| 1632 |
region. |
| 1633 |
|
| 1634 |
Setting the address to 0 will result in resetting the address to its default |
| 1635 |
(0xfffbc000). |
| 1636 |
|
| 1637 |
This ioctl is required on Intel-based hosts. This is needed on Intel hardware |
| 1638 |
because of a quirk in the virtualization implementation (see the internals |
| 1639 |
documentation when it pops into existence). |
| 1640 |
|
| 1641 |
Fails if any VCPU has already been created. |
| 1642 |
|
| 1643 |
4.41 KVM_SET_BOOT_CPU_ID |
| 1644 |
------------------------ |
| 1645 |
|
| 1646 |
:Capability: KVM_CAP_SET_BOOT_CPU_ID |
| 1647 |
:Architectures: x86 |
| 1648 |
:Type: vm ioctl |
| 1649 |
:Parameters: unsigned long vcpu_id |
| 1650 |
:Returns: 0 on success, -1 on error |
| 1651 |
|
| 1652 |
Define which vcpu is the Bootstrap Processor (BSP). Values are the same |
| 1653 |
as the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the default |
| 1654 |
is vcpu 0. This ioctl has to be called before vcpu creation, |
| 1655 |
otherwise it will return EBUSY error. |
| 1656 |
|
| 1657 |
|
| 1658 |
4.42 KVM_GET_XSAVE |
| 1659 |
------------------ |
| 1660 |
|
| 1661 |
:Capability: KVM_CAP_XSAVE |
| 1662 |
:Architectures: x86 |
| 1663 |
:Type: vcpu ioctl |
| 1664 |
:Parameters: struct kvm_xsave (out) |
| 1665 |
:Returns: 0 on success, -1 on error |
| 1666 |
|
| 1667 |
|
| 1668 |
:: |
| 1669 |
|
| 1670 |
struct kvm_xsave { |
| 1671 |
__u32 region[1024]; |
| 1672 |
__u32 extra[0]; |
| 1673 |
}; |
| 1674 |
|
| 1675 |
This ioctl would copy current vcpu's xsave struct to the userspace. |
| 1676 |
|
| 1677 |
|
| 1678 |
4.43 KVM_SET_XSAVE |
| 1679 |
------------------ |
| 1680 |
|
| 1681 |
:Capability: KVM_CAP_XSAVE and KVM_CAP_XSAVE2 |
| 1682 |
:Architectures: x86 |
| 1683 |
:Type: vcpu ioctl |
| 1684 |
:Parameters: struct kvm_xsave (in) |
| 1685 |
:Returns: 0 on success, -1 on error |
| 1686 |
|
| 1687 |
:: |
| 1688 |
|
| 1689 |
|
| 1690 |
struct kvm_xsave { |
| 1691 |
__u32 region[1024]; |
| 1692 |
__u32 extra[0]; |
| 1693 |
}; |
| 1694 |
|
| 1695 |
This ioctl would copy userspace's xsave struct to the kernel. It copies |
| 1696 |
as many bytes as are returned by KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2), |
| 1697 |
when invoked on the vm file descriptor. The size value returned by |
| 1698 |
KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2) will always be at least 4096. |
| 1699 |
Currently, it is only greater than 4096 if a dynamic feature has been |
| 1700 |
enabled with ``arch_prctl()``, but this may change in the future. |
| 1701 |
|
| 1702 |
The offsets of the state save areas in struct kvm_xsave follow the |
| 1703 |
contents of CPUID leaf 0xD on the host. |
| 1704 |
|
| 1705 |
|
| 1706 |
4.44 KVM_GET_XCRS |
| 1707 |
----------------- |
| 1708 |
|
| 1709 |
:Capability: KVM_CAP_XCRS |
| 1710 |
:Architectures: x86 |
| 1711 |
:Type: vcpu ioctl |
| 1712 |
:Parameters: struct kvm_xcrs (out) |
| 1713 |
:Returns: 0 on success, -1 on error |
| 1714 |
|
| 1715 |
:: |
| 1716 |
|
| 1717 |
struct kvm_xcr { |
| 1718 |
__u32 xcr; |
| 1719 |
__u32 reserved; |
| 1720 |
__u64 value; |
| 1721 |
}; |
| 1722 |
|
| 1723 |
struct kvm_xcrs { |
| 1724 |
__u32 nr_xcrs; |
| 1725 |
__u32 flags; |
| 1726 |
struct kvm_xcr xcrs[KVM_MAX_XCRS]; |
| 1727 |
__u64 padding[16]; |
| 1728 |
}; |
| 1729 |
|
| 1730 |
This ioctl would copy current vcpu's xcrs to the userspace. |
| 1731 |
|
| 1732 |
|
| 1733 |
4.45 KVM_SET_XCRS |
| 1734 |
----------------- |
| 1735 |
|
| 1736 |
:Capability: KVM_CAP_XCRS |
| 1737 |
:Architectures: x86 |
| 1738 |
:Type: vcpu ioctl |
| 1739 |
:Parameters: struct kvm_xcrs (in) |
| 1740 |
:Returns: 0 on success, -1 on error |
| 1741 |
|
| 1742 |
:: |
| 1743 |
|
| 1744 |
struct kvm_xcr { |
| 1745 |
__u32 xcr; |
| 1746 |
__u32 reserved; |
| 1747 |
__u64 value; |
| 1748 |
}; |
| 1749 |
|
| 1750 |
struct kvm_xcrs { |
| 1751 |
__u32 nr_xcrs; |
| 1752 |
__u32 flags; |
| 1753 |
struct kvm_xcr xcrs[KVM_MAX_XCRS]; |
| 1754 |
__u64 padding[16]; |
| 1755 |
}; |
| 1756 |
|
| 1757 |
This ioctl would set vcpu's xcr to the value userspace specified. |
| 1758 |
|
| 1759 |
|
| 1760 |
4.46 KVM_GET_SUPPORTED_CPUID |
| 1761 |
---------------------------- |
| 1762 |
|
| 1763 |
:Capability: KVM_CAP_EXT_CPUID |
| 1764 |
:Architectures: x86 |
| 1765 |
:Type: system ioctl |
| 1766 |
:Parameters: struct kvm_cpuid2 (in/out) |
| 1767 |
:Returns: 0 on success, -1 on error |
| 1768 |
|
| 1769 |
:: |
| 1770 |
|
| 1771 |
struct kvm_cpuid2 { |
| 1772 |
__u32 nent; |
| 1773 |
__u32 padding; |
| 1774 |
struct kvm_cpuid_entry2 entries[0]; |
| 1775 |
}; |
| 1776 |
|
| 1777 |
#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0) |
| 1778 |
#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1) /* deprecated */ |
| 1779 |
#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2) /* deprecated */ |
| 1780 |
|
| 1781 |
struct kvm_cpuid_entry2 { |
| 1782 |
__u32 function; |
| 1783 |
__u32 index; |
| 1784 |
__u32 flags; |
| 1785 |
__u32 eax; |
| 1786 |
__u32 ebx; |
| 1787 |
__u32 ecx; |
| 1788 |
__u32 edx; |
| 1789 |
__u32 padding[3]; |
| 1790 |
}; |
| 1791 |
|
| 1792 |
This ioctl returns x86 cpuid features which are supported by both the |
| 1793 |
hardware and kvm in its default configuration. Userspace can use the |
| 1794 |
information returned by this ioctl to construct cpuid information (for |
| 1795 |
KVM_SET_CPUID2) that is consistent with hardware, kernel, and |
| 1796 |
userspace capabilities, and with user requirements (for example, the |
| 1797 |
user may wish to constrain cpuid to emulate older hardware, or for |
| 1798 |
feature consistency across a cluster). |
| 1799 |
|
| 1800 |
Dynamically-enabled feature bits need to be requested with |
| 1801 |
``arch_prctl()`` before calling this ioctl. Feature bits that have not |
| 1802 |
been requested are excluded from the result. |
| 1803 |
|
| 1804 |
Note that certain capabilities, such as KVM_CAP_X86_DISABLE_EXITS, may |
| 1805 |
expose cpuid features (e.g. MONITOR) which are not supported by kvm in |
| 1806 |
its default configuration. If userspace enables such capabilities, it |
| 1807 |
is responsible for modifying the results of this ioctl appropriately. |
| 1808 |
|
| 1809 |
Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structure |
| 1810 |
with the 'nent' field indicating the number of entries in the variable-size |
| 1811 |
array 'entries'. If the number of entries is too low to describe the cpu |
| 1812 |
capabilities, an error (E2BIG) is returned. If the number is too high, |
| 1813 |
the 'nent' field is adjusted and an error (ENOMEM) is returned. If the |
| 1814 |
number is just right, the 'nent' field is adjusted to the number of valid |
| 1815 |
entries in the 'entries' array, which is then filled. |
| 1816 |
|
| 1817 |
The entries returned are the host cpuid as returned by the cpuid instruction, |
| 1818 |
with unknown or unsupported features masked out. Some features (for example, |
| 1819 |
x2apic), may not be present in the host cpu, but are exposed by kvm if it can |
| 1820 |
emulate them efficiently. The fields in each entry are defined as follows: |
| 1821 |
|
| 1822 |
function: |
| 1823 |
the eax value used to obtain the entry |
| 1824 |
|
| 1825 |
index: |
| 1826 |
the ecx value used to obtain the entry (for entries that are |
| 1827 |
affected by ecx) |
| 1828 |
|
| 1829 |
flags: |
| 1830 |
an OR of zero or more of the following: |
| 1831 |
|
| 1832 |
KVM_CPUID_FLAG_SIGNIFCANT_INDEX: |
| 1833 |
if the index field is valid |
| 1834 |
|
| 1835 |
eax, ebx, ecx, edx: |
| 1836 |
the values returned by the cpuid instruction for |
| 1837 |
this function/index combination |
| 1838 |
|
| 1839 |
x2APIC (CPUID leaf 1, ecx[21) and TSC deadline timer (CPUID leaf 1, ecx[24]) |
| 1840 |
may be returned as true, but they depend on KVM_CREATE_IRQCHIP for in-kernel |
| 1841 |
emulation of the local APIC. TSC deadline timer support is also reported via:: |
| 1842 |
|
| 1843 |
ioctl(KVM_CHECK_EXTENSION, KVM_CAP_TSC_DEADLINE_TIMER) |
| 1844 |
|
| 1845 |
if that returns true and you use KVM_CREATE_IRQCHIP, or if you emulate the |
| 1846 |
feature in userspace, then you can enable the feature for KVM_SET_CPUID2. |
| 1847 |
|
| 1848 |
Enabling x2APIC in KVM_SET_CPUID2 requires KVM_CREATE_IRQCHIP as KVM doesn't |
| 1849 |
support forwarding x2APIC MSR accesses to userspace, i.e. KVM does not support |
| 1850 |
emulating x2APIC in userspace. |
| 1851 |
|
| 1852 |
4.47 KVM_PPC_GET_PVINFO |
| 1853 |
----------------------- |
| 1854 |
|
| 1855 |
:Capability: KVM_CAP_PPC_GET_PVINFO |
| 1856 |
:Architectures: ppc |
| 1857 |
:Type: vm ioctl |
| 1858 |
:Parameters: struct kvm_ppc_pvinfo (out) |
| 1859 |
:Returns: 0 on success, !0 on error |
| 1860 |
|
| 1861 |
:: |
| 1862 |
|
| 1863 |
struct kvm_ppc_pvinfo { |
| 1864 |
__u32 flags; |
| 1865 |
__u32 hcall[4]; |
| 1866 |
__u8 pad[108]; |
| 1867 |
}; |
| 1868 |
|
| 1869 |
This ioctl fetches PV specific information that need to be passed to the guest |
| 1870 |
using the device tree or other means from vm context. |
| 1871 |
|
| 1872 |
The hcall array defines 4 instructions that make up a hypercall. |
| 1873 |
|
| 1874 |
If any additional field gets added to this structure later on, a bit for that |
| 1875 |
additional piece of information will be set in the flags bitmap. |
| 1876 |
|
| 1877 |
The flags bitmap is defined as:: |
| 1878 |
|
| 1879 |
/* the host supports the ePAPR idle hcall |
| 1880 |
#define KVM_PPC_PVINFO_FLAGS_EV_IDLE (1<<0) |
| 1881 |
|
| 1882 |
4.52 KVM_SET_GSI_ROUTING |
| 1883 |
------------------------ |
| 1884 |
|
| 1885 |
:Capability: KVM_CAP_IRQ_ROUTING |
| 1886 |
:Architectures: x86 s390 arm64 |
| 1887 |
:Type: vm ioctl |
| 1888 |
:Parameters: struct kvm_irq_routing (in) |
| 1889 |
:Returns: 0 on success, -1 on error |
| 1890 |
|
| 1891 |
Sets the GSI routing table entries, overwriting any previously set entries. |
| 1892 |
|
| 1893 |
On arm64, GSI routing has the following limitation: |
| 1894 |
|
| 1895 |
- GSI routing does not apply to KVM_IRQ_LINE but only to KVM_IRQFD. |
| 1896 |
|
| 1897 |
:: |
| 1898 |
|
| 1899 |
struct kvm_irq_routing { |
| 1900 |
__u32 nr; |
| 1901 |
__u32 flags; |
| 1902 |
struct kvm_irq_routing_entry entries[0]; |
| 1903 |
}; |
| 1904 |
|
| 1905 |
No flags are specified so far, the corresponding field must be set to zero. |
| 1906 |
|
| 1907 |
:: |
| 1908 |
|
| 1909 |
struct kvm_irq_routing_entry { |
| 1910 |
__u32 gsi; |
| 1911 |
__u32 type; |
| 1912 |
__u32 flags; |
| 1913 |
__u32 pad; |
| 1914 |
union { |
| 1915 |
struct kvm_irq_routing_irqchip irqchip; |
| 1916 |
struct kvm_irq_routing_msi msi; |
| 1917 |
struct kvm_irq_routing_s390_adapter adapter; |
| 1918 |
struct kvm_irq_routing_hv_sint hv_sint; |
| 1919 |
struct kvm_irq_routing_xen_evtchn xen_evtchn; |
| 1920 |
__u32 pad[8]; |
| 1921 |
} u; |
| 1922 |
}; |
| 1923 |
|
| 1924 |
/* gsi routing entry types */ |
| 1925 |
#define KVM_IRQ_ROUTING_IRQCHIP 1 |
| 1926 |
#define KVM_IRQ_ROUTING_MSI 2 |
| 1927 |
#define KVM_IRQ_ROUTING_S390_ADAPTER 3 |
| 1928 |
#define KVM_IRQ_ROUTING_HV_SINT 4 |
| 1929 |
#define KVM_IRQ_ROUTING_XEN_EVTCHN 5 |
| 1930 |
|
| 1931 |
On s390, adding a KVM_IRQ_ROUTING_S390_ADAPTER is rejected on ucontrol VMs with |
| 1932 |
error -EINVAL. |
| 1933 |
|
| 1934 |
flags: |
| 1935 |
|
| 1936 |
- KVM_MSI_VALID_DEVID: used along with KVM_IRQ_ROUTING_MSI routing entry |
| 1937 |
type, specifies that the devid field contains a valid value. The per-VM |
| 1938 |
KVM_CAP_MSI_DEVID capability advertises the requirement to provide |
| 1939 |
the device ID. If this capability is not available, userspace should |
| 1940 |
never set the KVM_MSI_VALID_DEVID flag as the ioctl might fail. |
| 1941 |
- zero otherwise |
| 1942 |
|
| 1943 |
:: |
| 1944 |
|
| 1945 |
struct kvm_irq_routing_irqchip { |
| 1946 |
__u32 irqchip; |
| 1947 |
__u32 pin; |
| 1948 |
}; |
| 1949 |
|
| 1950 |
struct kvm_irq_routing_msi { |
| 1951 |
__u32 address_lo; |
| 1952 |
__u32 address_hi; |
| 1953 |
__u32 data; |
| 1954 |
union { |
| 1955 |
__u32 pad; |
| 1956 |
__u32 devid; |
| 1957 |
}; |
| 1958 |
}; |
| 1959 |
|
| 1960 |
If KVM_MSI_VALID_DEVID is set, devid contains a unique device identifier |
| 1961 |
for the device that wrote the MSI message. For PCI, this is usually a |
| 1962 |
BDF identifier in the lower 16 bits. |
| 1963 |
|
| 1964 |
On x86, address_hi is ignored unless the KVM_X2APIC_API_USE_32BIT_IDS |
| 1965 |
feature of KVM_CAP_X2APIC_API capability is enabled. If it is enabled, |
| 1966 |
address_hi bits 31-8 provide bits 31-8 of the destination id. Bits 7-0 of |
| 1967 |
address_hi must be zero. |
| 1968 |
|
| 1969 |
:: |
| 1970 |
|
| 1971 |
struct kvm_irq_routing_s390_adapter { |
| 1972 |
__u64 ind_addr; |
| 1973 |
__u64 summary_addr; |
| 1974 |
__u64 ind_offset; |
| 1975 |
__u32 summary_offset; |
| 1976 |
__u32 adapter_id; |
| 1977 |
}; |
| 1978 |
|
| 1979 |
struct kvm_irq_routing_hv_sint { |
| 1980 |
__u32 vcpu; |
| 1981 |
__u32 sint; |
| 1982 |
}; |
| 1983 |
|
| 1984 |
struct kvm_irq_routing_xen_evtchn { |
| 1985 |
__u32 port; |
| 1986 |
__u32 vcpu; |
| 1987 |
__u32 priority; |
| 1988 |
}; |
| 1989 |
|
| 1990 |
|
| 1991 |
When KVM_CAP_XEN_HVM includes the KVM_XEN_HVM_CONFIG_EVTCHN_2LEVEL bit |
| 1992 |
in its indication of supported features, routing to Xen event channels |
| 1993 |
is supported. Although the priority field is present, only the value |
| 1994 |
KVM_XEN_HVM_CONFIG_EVTCHN_2LEVEL is supported, which means delivery by |
| 1995 |
2 level event channels. FIFO event channel support may be added in |
| 1996 |
the future. |
| 1997 |
|
| 1998 |
|
| 1999 |
4.55 KVM_SET_TSC_KHZ |
| 2000 |
-------------------- |
| 2001 |
|
| 2002 |
:Capability: KVM_CAP_TSC_CONTROL / KVM_CAP_VM_TSC_CONTROL |
| 2003 |
:Architectures: x86 |
| 2004 |
:Type: vcpu ioctl / vm ioctl |
| 2005 |
:Parameters: virtual tsc_khz |
| 2006 |
:Returns: 0 on success, -1 on error |
| 2007 |
|
| 2008 |
Specifies the tsc frequency for the virtual machine. The unit of the |
| 2009 |
frequency is KHz. |
| 2010 |
|
| 2011 |
If the KVM_CAP_VM_TSC_CONTROL capability is advertised, this can also |
| 2012 |
be used as a vm ioctl to set the initial tsc frequency of subsequently |
| 2013 |
created vCPUs. Note, the vm ioctl is only allowed prior to creating vCPUs. |
| 2014 |
|
| 2015 |
For TSC protected Confidential Computing (CoCo) VMs where TSC frequency |
| 2016 |
is configured once at VM scope and remains unchanged during VM's |
| 2017 |
lifetime, the vm ioctl should be used to configure the TSC frequency |
| 2018 |
and the vcpu ioctl is not supported. |
| 2019 |
|
| 2020 |
Example of such CoCo VMs: TDX guests. |
| 2021 |
|
| 2022 |
4.56 KVM_GET_TSC_KHZ |
| 2023 |
-------------------- |
| 2024 |
|
| 2025 |
:Capability: KVM_CAP_GET_TSC_KHZ / KVM_CAP_VM_TSC_CONTROL |
| 2026 |
:Architectures: x86 |
| 2027 |
:Type: vcpu ioctl / vm ioctl |
| 2028 |
:Parameters: none |
| 2029 |
:Returns: virtual tsc-khz on success, negative value on error |
| 2030 |
|
| 2031 |
Returns the tsc frequency of the guest. The unit of the return value is |
| 2032 |
KHz. If the host has unstable tsc this ioctl returns -EIO instead as an |
| 2033 |
error. |
| 2034 |
|
| 2035 |
|
| 2036 |
4.57 KVM_GET_LAPIC |
| 2037 |
------------------ |
| 2038 |
|
| 2039 |
:Capability: KVM_CAP_IRQCHIP |
| 2040 |
:Architectures: x86 |
| 2041 |
:Type: vcpu ioctl |
| 2042 |
:Parameters: struct kvm_lapic_state (out) |
| 2043 |
:Returns: 0 on success, -1 on error |
| 2044 |
|
| 2045 |
:: |
| 2046 |
|
| 2047 |
#define KVM_APIC_REG_SIZE 0x400 |
| 2048 |
struct kvm_lapic_state { |
| 2049 |
char regs[KVM_APIC_REG_SIZE]; |
| 2050 |
}; |
| 2051 |
|
| 2052 |
Reads the Local APIC registers and copies them into the input argument. The |
| 2053 |
data format and layout are the same as documented in the architecture manual. |
| 2054 |
|
| 2055 |
If KVM_X2APIC_API_USE_32BIT_IDS feature of KVM_CAP_X2APIC_API is |
| 2056 |
enabled, then the format of APIC_ID register depends on the APIC mode |
| 2057 |
(reported by MSR_IA32_APICBASE) of its VCPU. x2APIC stores APIC ID in |
| 2058 |
the APIC_ID register (bytes 32-35). xAPIC only allows an 8-bit APIC ID |
| 2059 |
which is stored in bits 31-24 of the APIC register, or equivalently in |
| 2060 |
byte 35 of struct kvm_lapic_state's regs field. KVM_GET_LAPIC must then |
| 2061 |
be called after MSR_IA32_APICBASE has been set with KVM_SET_MSR. |
| 2062 |
|
| 2063 |
If KVM_X2APIC_API_USE_32BIT_IDS feature is disabled, struct kvm_lapic_state |
| 2064 |
always uses xAPIC format. |
| 2065 |
|
| 2066 |
|
| 2067 |
4.58 KVM_SET_LAPIC |
| 2068 |
------------------ |
| 2069 |
|
| 2070 |
:Capability: KVM_CAP_IRQCHIP |
| 2071 |
:Architectures: x86 |
| 2072 |
:Type: vcpu ioctl |
| 2073 |
:Parameters: struct kvm_lapic_state (in) |
| 2074 |
:Returns: 0 on success, -1 on error |
| 2075 |
|
| 2076 |
:: |
| 2077 |
|
| 2078 |
#define KVM_APIC_REG_SIZE 0x400 |
| 2079 |
struct kvm_lapic_state { |
| 2080 |
char regs[KVM_APIC_REG_SIZE]; |
| 2081 |
}; |
| 2082 |
|
| 2083 |
Copies the input argument into the Local APIC registers. The data format |
| 2084 |
and layout are the same as documented in the architecture manual. |
| 2085 |
|
| 2086 |
The format of the APIC ID register (bytes 32-35 of struct kvm_lapic_state's |
| 2087 |
regs field) depends on the state of the KVM_CAP_X2APIC_API capability. |
| 2088 |
See the note in KVM_GET_LAPIC. |
| 2089 |
|
| 2090 |
|
| 2091 |
4.59 KVM_IOEVENTFD |
| 2092 |
------------------ |
| 2093 |
|
| 2094 |
:Capability: KVM_CAP_IOEVENTFD |
| 2095 |
:Architectures: all |
| 2096 |
:Type: vm ioctl |
| 2097 |
:Parameters: struct kvm_ioeventfd (in) |
| 2098 |
:Returns: 0 on success, !0 on error |
| 2099 |
|
| 2100 |
This ioctl attaches or detaches an ioeventfd to a legal pio/mmio address |
| 2101 |
within the guest. A guest write in the registered address will signal the |
| 2102 |
provided event instead of triggering an exit. |
| 2103 |
|
| 2104 |
:: |
| 2105 |
|
| 2106 |
struct kvm_ioeventfd { |
| 2107 |
__u64 datamatch; |
| 2108 |
__u64 addr; /* legal pio/mmio address */ |
| 2109 |
__u32 len; /* 0, 1, 2, 4, or 8 bytes */ |
| 2110 |
__s32 fd; |
| 2111 |
__u32 flags; |
| 2112 |
__u8 pad[36]; |
| 2113 |
}; |
| 2114 |
|
| 2115 |
For the special case of virtio-ccw devices on s390, the ioevent is matched |
| 2116 |
to a subchannel/virtqueue tuple instead. |
| 2117 |
|
| 2118 |
The following flags are defined:: |
| 2119 |
|
| 2120 |
#define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch) |
| 2121 |
#define KVM_IOEVENTFD_FLAG_PIO (1 << kvm_ioeventfd_flag_nr_pio) |
| 2122 |
#define KVM_IOEVENTFD_FLAG_DEASSIGN (1 << kvm_ioeventfd_flag_nr_deassign) |
| 2123 |
#define KVM_IOEVENTFD_FLAG_VIRTIO_CCW_NOTIFY \ |
| 2124 |
(1 << kvm_ioeventfd_flag_nr_virtio_ccw_notify) |
| 2125 |
|
| 2126 |
If datamatch flag is set, the event will be signaled only if the written value |
| 2127 |
to the registered address is equal to datamatch in struct kvm_ioeventfd. |
| 2128 |
|
| 2129 |
For virtio-ccw devices, addr contains the subchannel id and datamatch the |
| 2130 |
virtqueue index. |
| 2131 |
|
| 2132 |
With KVM_CAP_IOEVENTFD_ANY_LENGTH, a zero length ioeventfd is allowed, and |
| 2133 |
the kernel will ignore the length of guest write and may get a faster vmexit. |
| 2134 |
The speedup may only apply to specific architectures, but the ioeventfd will |
| 2135 |
work anyway. |
| 2136 |
|
| 2137 |
4.60 KVM_DIRTY_TLB |
| 2138 |
------------------ |
| 2139 |
|
| 2140 |
:Capability: KVM_CAP_SW_TLB |
| 2141 |
:Architectures: ppc |
| 2142 |
:Type: vcpu ioctl |
| 2143 |
:Parameters: struct kvm_dirty_tlb (in) |
| 2144 |
:Returns: 0 on success, -1 on error |
| 2145 |
|
| 2146 |
:: |
| 2147 |
|
| 2148 |
struct kvm_dirty_tlb { |
| 2149 |
__u64 bitmap; |
| 2150 |
__u32 num_dirty; |
| 2151 |
}; |
| 2152 |
|
| 2153 |
This must be called whenever userspace has changed an entry in the shared |
| 2154 |
TLB, prior to calling KVM_RUN on the associated vcpu. |
| 2155 |
|
| 2156 |
The "bitmap" field is the userspace address of an array. This array |
| 2157 |
consists of a number of bits, equal to the total number of TLB entries as |
| 2158 |
determined by the last successful call to ``KVM_ENABLE_CAP(KVM_CAP_SW_TLB)``, |
| 2159 |
rounded up to the nearest multiple of 64. |
| 2160 |
|
| 2161 |
Each bit corresponds to one TLB entry, ordered the same as in the shared TLB |
| 2162 |
array. |
| 2163 |
|
| 2164 |
The array is little-endian: the bit 0 is the least significant bit of the |
| 2165 |
first byte, bit 8 is the least significant bit of the second byte, etc. |
| 2166 |
This avoids any complications with differing word sizes. |
| 2167 |
|
| 2168 |
The "num_dirty" field is a performance hint for KVM to determine whether it |
| 2169 |
should skip processing the bitmap and just invalidate everything. It must |
| 2170 |
be set to the number of set bits in the bitmap. |
| 2171 |
|
| 2172 |
|
| 2173 |
4.62 KVM_CREATE_SPAPR_TCE |
| 2174 |
------------------------- |
| 2175 |
|
| 2176 |
:Capability: KVM_CAP_SPAPR_TCE |
| 2177 |
:Architectures: powerpc |
| 2178 |
:Type: vm ioctl |
| 2179 |
:Parameters: struct kvm_create_spapr_tce (in) |
| 2180 |
:Returns: file descriptor for manipulating the created TCE table |
| 2181 |
|
| 2182 |
This creates a virtual TCE (translation control entry) table, which |
| 2183 |
is an IOMMU for PAPR-style virtual I/O. It is used to translate |
| 2184 |
logical addresses used in virtual I/O into guest physical addresses, |
| 2185 |
and provides a scatter/gather capability for PAPR virtual I/O. |
| 2186 |
|
| 2187 |
:: |
| 2188 |
|
| 2189 |
/* for KVM_CAP_SPAPR_TCE */ |
| 2190 |
struct kvm_create_spapr_tce { |
| 2191 |
__u64 liobn; |
| 2192 |
__u32 window_size; |
| 2193 |
}; |
| 2194 |
|
| 2195 |
The liobn field gives the logical IO bus number for which to create a |
| 2196 |
TCE table. The window_size field specifies the size of the DMA window |
| 2197 |
which this TCE table will translate - the table will contain one 64 |
| 2198 |
bit TCE entry for every 4kiB of the DMA window. |
| 2199 |
|
| 2200 |
When the guest issues an H_PUT_TCE hcall on a liobn for which a TCE |
| 2201 |
table has been created using this ioctl(), the kernel will handle it |
| 2202 |
in real mode, updating the TCE table. H_PUT_TCE calls for other |
| 2203 |
liobns will cause a vm exit and must be handled by userspace. |
| 2204 |
|
| 2205 |
The return value is a file descriptor which can be passed to mmap(2) |
| 2206 |
to map the created TCE table into userspace. This lets userspace read |
| 2207 |
the entries written by kernel-handled H_PUT_TCE calls, and also lets |
| 2208 |
userspace update the TCE table directly which is useful in some |
| 2209 |
circumstances. |
| 2210 |
|
| 2211 |
|
| 2212 |
4.64 KVM_NMI |
| 2213 |
------------ |
| 2214 |
|
| 2215 |
:Capability: KVM_CAP_USER_NMI |
| 2216 |
:Architectures: x86 |
| 2217 |
:Type: vcpu ioctl |
| 2218 |
:Parameters: none |
| 2219 |
:Returns: 0 on success, -1 on error |
| 2220 |
|
| 2221 |
Queues an NMI on the thread's vcpu. Note this is well defined only |
| 2222 |
when KVM_CREATE_IRQCHIP has not been called, since this is an interface |
| 2223 |
between the virtual cpu core and virtual local APIC. After KVM_CREATE_IRQCHIP |
| 2224 |
has been called, this interface is completely emulated within the kernel. |
| 2225 |
|
| 2226 |
To use this to emulate the LINT1 input with KVM_CREATE_IRQCHIP, use the |
| 2227 |
following algorithm: |
| 2228 |
|
| 2229 |
- pause the vcpu |
| 2230 |
- read the local APIC's state (KVM_GET_LAPIC) |
| 2231 |
- check whether changing LINT1 will queue an NMI (see the LVT entry for LINT1) |
| 2232 |
- if so, issue KVM_NMI |
| 2233 |
- resume the vcpu |
| 2234 |
|
| 2235 |
Some guests configure the LINT1 NMI input to cause a panic, aiding in |
| 2236 |
debugging. |
| 2237 |
|
| 2238 |
|
| 2239 |
4.65 KVM_S390_UCAS_MAP |
| 2240 |
---------------------- |
| 2241 |
|
| 2242 |
:Capability: KVM_CAP_S390_UCONTROL |
| 2243 |
:Architectures: s390 |
| 2244 |
:Type: vcpu ioctl |
| 2245 |
:Parameters: struct kvm_s390_ucas_mapping (in) |
| 2246 |
:Returns: 0 in case of success |
| 2247 |
|
| 2248 |
The parameter is defined like this:: |
| 2249 |
|
| 2250 |
struct kvm_s390_ucas_mapping { |
| 2251 |
__u64 user_addr; |
| 2252 |
__u64 vcpu_addr; |
| 2253 |
__u64 length; |
| 2254 |
}; |
| 2255 |
|
| 2256 |
This ioctl maps the memory at "user_addr" with the length "length" to |
| 2257 |
the vcpu's address space starting at "vcpu_addr". All parameters need to |
| 2258 |
be aligned by 1 megabyte. |
| 2259 |
|
| 2260 |
|
| 2261 |
4.66 KVM_S390_UCAS_UNMAP |
| 2262 |
------------------------ |
| 2263 |
|
| 2264 |
:Capability: KVM_CAP_S390_UCONTROL |
| 2265 |
:Architectures: s390 |
| 2266 |
:Type: vcpu ioctl |
| 2267 |
:Parameters: struct kvm_s390_ucas_mapping (in) |
| 2268 |
:Returns: 0 in case of success |
| 2269 |
|
| 2270 |
The parameter is defined like this:: |
| 2271 |
|
| 2272 |
struct kvm_s390_ucas_mapping { |
| 2273 |
__u64 user_addr; |
| 2274 |
__u64 vcpu_addr; |
| 2275 |
__u64 length; |
| 2276 |
}; |
| 2277 |
|
| 2278 |
This ioctl unmaps the memory in the vcpu's address space starting at |
| 2279 |
"vcpu_addr" with the length "length". The field "user_addr" is ignored. |
| 2280 |
All parameters need to be aligned by 1 megabyte. |
| 2281 |
|
| 2282 |
|
| 2283 |
4.67 KVM_S390_VCPU_FAULT |
| 2284 |
------------------------ |
| 2285 |
|
| 2286 |
:Capability: KVM_CAP_S390_UCONTROL |
| 2287 |
:Architectures: s390 |
| 2288 |
:Type: vcpu ioctl |
| 2289 |
:Parameters: vcpu absolute address (in) |
| 2290 |
:Returns: 0 in case of success |
| 2291 |
|
| 2292 |
This call creates a page table entry on the virtual cpu's address space |
| 2293 |
(for user controlled virtual machines) or the virtual machine's address |
| 2294 |
space (for regular virtual machines). This only works for minor faults, |
| 2295 |
thus it's recommended to access subject memory page via the user page |
| 2296 |
table upfront. This is useful to handle validity intercepts for user |
| 2297 |
controlled virtual machines to fault in the virtual cpu's lowcore pages |
| 2298 |
prior to calling the KVM_RUN ioctl. |
| 2299 |
|
| 2300 |
|
| 2301 |
4.68 KVM_SET_ONE_REG |
| 2302 |
-------------------- |
| 2303 |
|
| 2304 |
:Capability: KVM_CAP_ONE_REG |
| 2305 |
:Architectures: all |
| 2306 |
:Type: vcpu ioctl |
| 2307 |
:Parameters: struct kvm_one_reg (in) |
| 2308 |
:Returns: 0 on success, negative value on failure |
| 2309 |
|
| 2310 |
Errors: |
| 2311 |
|
| 2312 |
====== ============================================================ |
| 2313 |
ENOENT no such register |
| 2314 |
EINVAL invalid register ID, or no such register or used with VMs in |
| 2315 |
protected virtualization mode on s390 |
| 2316 |
EPERM (arm64) register access not allowed before vcpu finalization |
| 2317 |
EBUSY (riscv) changing register value not allowed after the vcpu |
| 2318 |
has run at least once |
| 2319 |
====== ============================================================ |
| 2320 |
|
| 2321 |
(These error codes are indicative only: do not rely on a specific error |
| 2322 |
code being returned in a specific situation.) |
| 2323 |
|
| 2324 |
:: |
| 2325 |
|
| 2326 |
struct kvm_one_reg { |
| 2327 |
__u64 id; |
| 2328 |
__u64 addr; |
| 2329 |
}; |
| 2330 |
|
| 2331 |
Using this ioctl, a single vcpu register can be set to a specific value |
| 2332 |
defined by user space with the passed in struct kvm_one_reg, where id |
| 2333 |
refers to the register identifier as described below and addr is a pointer |
| 2334 |
to a variable with the respective size. There can be architecture agnostic |
| 2335 |
and architecture specific registers. Each have their own range of operation |
| 2336 |
and their own constants and width. To keep track of the implemented |
| 2337 |
registers, find a list below: |
| 2338 |
|
| 2339 |
======= =============================== ============ |
| 2340 |
Arch Register Width (bits) |
| 2341 |
======= =============================== ============ |
| 2342 |
PPC KVM_REG_PPC_HIOR 64 |
| 2343 |
PPC KVM_REG_PPC_IAC1 64 |
| 2344 |
PPC KVM_REG_PPC_IAC2 64 |
| 2345 |
PPC KVM_REG_PPC_IAC3 64 |
| 2346 |
PPC KVM_REG_PPC_IAC4 64 |
| 2347 |
PPC KVM_REG_PPC_DAC1 64 |
| 2348 |
PPC KVM_REG_PPC_DAC2 64 |
| 2349 |
PPC KVM_REG_PPC_DABR 64 |
| 2350 |
PPC KVM_REG_PPC_DSCR 64 |
| 2351 |
PPC KVM_REG_PPC_PURR 64 |
| 2352 |
PPC KVM_REG_PPC_SPURR 64 |
| 2353 |
PPC KVM_REG_PPC_DAR 64 |
| 2354 |
PPC KVM_REG_PPC_DSISR 32 |
| 2355 |
PPC KVM_REG_PPC_AMR 64 |
| 2356 |
PPC KVM_REG_PPC_UAMOR 64 |
| 2357 |
PPC KVM_REG_PPC_MMCR0 64 |
| 2358 |
PPC KVM_REG_PPC_MMCR1 64 |
| 2359 |
PPC KVM_REG_PPC_MMCRA 64 |
| 2360 |
PPC KVM_REG_PPC_MMCR2 64 |
| 2361 |
PPC KVM_REG_PPC_MMCRS 64 |
| 2362 |
PPC KVM_REG_PPC_MMCR3 64 |
| 2363 |
PPC KVM_REG_PPC_SIAR 64 |
| 2364 |
PPC KVM_REG_PPC_SDAR 64 |
| 2365 |
PPC KVM_REG_PPC_SIER 64 |
| 2366 |
PPC KVM_REG_PPC_SIER2 64 |
| 2367 |
PPC KVM_REG_PPC_SIER3 64 |
| 2368 |
PPC KVM_REG_PPC_PMC1 32 |
| 2369 |
PPC KVM_REG_PPC_PMC2 32 |
| 2370 |
PPC KVM_REG_PPC_PMC3 32 |
| 2371 |
PPC KVM_REG_PPC_PMC4 32 |
| 2372 |
PPC KVM_REG_PPC_PMC5 32 |
| 2373 |
PPC KVM_REG_PPC_PMC6 32 |
| 2374 |
PPC KVM_REG_PPC_PMC7 32 |
| 2375 |
PPC KVM_REG_PPC_PMC8 32 |
| 2376 |
PPC KVM_REG_PPC_FPR0 64 |
| 2377 |
... |
| 2378 |
PPC KVM_REG_PPC_FPR31 64 |
| 2379 |
PPC KVM_REG_PPC_VR0 128 |
| 2380 |
... |
| 2381 |
PPC KVM_REG_PPC_VR31 128 |
| 2382 |
PPC KVM_REG_PPC_VSR0 128 |
| 2383 |
... |
| 2384 |
PPC KVM_REG_PPC_VSR31 128 |
| 2385 |
PPC KVM_REG_PPC_FPSCR 64 |
| 2386 |
PPC KVM_REG_PPC_VSCR 32 |
| 2387 |
PPC KVM_REG_PPC_VPA_ADDR 64 |
| 2388 |
PPC KVM_REG_PPC_VPA_SLB 128 |
| 2389 |
PPC KVM_REG_PPC_VPA_DTL 128 |
| 2390 |
PPC KVM_REG_PPC_EPCR 32 |
| 2391 |
PPC KVM_REG_PPC_EPR 32 |
| 2392 |
PPC KVM_REG_PPC_TCR 32 |
| 2393 |
PPC KVM_REG_PPC_TSR 32 |
| 2394 |
PPC KVM_REG_PPC_OR_TSR 32 |
| 2395 |
PPC KVM_REG_PPC_CLEAR_TSR 32 |
| 2396 |
PPC KVM_REG_PPC_MAS0 32 |
| 2397 |
PPC KVM_REG_PPC_MAS1 32 |
| 2398 |
PPC KVM_REG_PPC_MAS2 64 |
| 2399 |
PPC KVM_REG_PPC_MAS7_3 64 |
| 2400 |
PPC KVM_REG_PPC_MAS4 32 |
| 2401 |
PPC KVM_REG_PPC_MAS6 32 |
| 2402 |
PPC KVM_REG_PPC_MMUCFG 32 |
| 2403 |
PPC KVM_REG_PPC_TLB0CFG 32 |
| 2404 |
PPC KVM_REG_PPC_TLB1CFG 32 |
| 2405 |
PPC KVM_REG_PPC_TLB2CFG 32 |
| 2406 |
PPC KVM_REG_PPC_TLB3CFG 32 |
| 2407 |
PPC KVM_REG_PPC_TLB0PS 32 |
| 2408 |
PPC KVM_REG_PPC_TLB1PS 32 |
| 2409 |
PPC KVM_REG_PPC_TLB2PS 32 |
| 2410 |
PPC KVM_REG_PPC_TLB3PS 32 |
| 2411 |
PPC KVM_REG_PPC_EPTCFG 32 |
| 2412 |
PPC KVM_REG_PPC_ICP_STATE 64 |
| 2413 |
PPC KVM_REG_PPC_VP_STATE 128 |
| 2414 |
PPC KVM_REG_PPC_TB_OFFSET 64 |
| 2415 |
PPC KVM_REG_PPC_SPMC1 32 |
| 2416 |
PPC KVM_REG_PPC_SPMC2 32 |
| 2417 |
PPC KVM_REG_PPC_IAMR 64 |
| 2418 |
PPC KVM_REG_PPC_TFHAR 64 |
| 2419 |
PPC KVM_REG_PPC_TFIAR 64 |
| 2420 |
PPC KVM_REG_PPC_TEXASR 64 |
| 2421 |
PPC KVM_REG_PPC_FSCR 64 |
| 2422 |
PPC KVM_REG_PPC_PSPB 32 |
| 2423 |
PPC KVM_REG_PPC_EBBHR 64 |
| 2424 |
PPC KVM_REG_PPC_EBBRR 64 |
| 2425 |
PPC KVM_REG_PPC_BESCR 64 |
| 2426 |
PPC KVM_REG_PPC_TAR 64 |
| 2427 |
PPC KVM_REG_PPC_DPDES 64 |
| 2428 |
PPC KVM_REG_PPC_DAWR 64 |
| 2429 |
PPC KVM_REG_PPC_DAWRX 64 |
| 2430 |
PPC KVM_REG_PPC_CIABR 64 |
| 2431 |
PPC KVM_REG_PPC_IC 64 |
| 2432 |
PPC KVM_REG_PPC_VTB 64 |
| 2433 |
PPC KVM_REG_PPC_CSIGR 64 |
| 2434 |
PPC KVM_REG_PPC_TACR 64 |
| 2435 |
PPC KVM_REG_PPC_TCSCR 64 |
| 2436 |
PPC KVM_REG_PPC_PID 64 |
| 2437 |
PPC KVM_REG_PPC_ACOP 64 |
| 2438 |
PPC KVM_REG_PPC_VRSAVE 32 |
| 2439 |
PPC KVM_REG_PPC_LPCR 32 |
| 2440 |
PPC KVM_REG_PPC_LPCR_64 64 |
| 2441 |
PPC KVM_REG_PPC_PPR 64 |
| 2442 |
PPC KVM_REG_PPC_ARCH_COMPAT 32 |
| 2443 |
PPC KVM_REG_PPC_DABRX 32 |
| 2444 |
PPC KVM_REG_PPC_WORT 64 |
| 2445 |
PPC KVM_REG_PPC_SPRG9 64 |
| 2446 |
PPC KVM_REG_PPC_DBSR 32 |
| 2447 |
PPC KVM_REG_PPC_TIDR 64 |
| 2448 |
PPC KVM_REG_PPC_PSSCR 64 |
| 2449 |
PPC KVM_REG_PPC_DEC_EXPIRY 64 |
| 2450 |
PPC KVM_REG_PPC_PTCR 64 |
| 2451 |
PPC KVM_REG_PPC_HASHKEYR 64 |
| 2452 |
PPC KVM_REG_PPC_HASHPKEYR 64 |
| 2453 |
PPC KVM_REG_PPC_DAWR1 64 |
| 2454 |
PPC KVM_REG_PPC_DAWRX1 64 |
| 2455 |
PPC KVM_REG_PPC_DEXCR 64 |
| 2456 |
PPC KVM_REG_PPC_TM_GPR0 64 |
| 2457 |
... |
| 2458 |
PPC KVM_REG_PPC_TM_GPR31 64 |
| 2459 |
PPC KVM_REG_PPC_TM_VSR0 128 |
| 2460 |
... |
| 2461 |
PPC KVM_REG_PPC_TM_VSR63 128 |
| 2462 |
PPC KVM_REG_PPC_TM_CR 64 |
| 2463 |
PPC KVM_REG_PPC_TM_LR 64 |
| 2464 |
PPC KVM_REG_PPC_TM_CTR 64 |
| 2465 |
PPC KVM_REG_PPC_TM_FPSCR 64 |
| 2466 |
PPC KVM_REG_PPC_TM_AMR 64 |
| 2467 |
PPC KVM_REG_PPC_TM_PPR 64 |
| 2468 |
PPC KVM_REG_PPC_TM_VRSAVE 64 |
| 2469 |
PPC KVM_REG_PPC_TM_VSCR 32 |
| 2470 |
PPC KVM_REG_PPC_TM_DSCR 64 |
| 2471 |
PPC KVM_REG_PPC_TM_TAR 64 |
| 2472 |
PPC KVM_REG_PPC_TM_XER 64 |
| 2473 |
|
| 2474 |
MIPS KVM_REG_MIPS_R0 64 |
| 2475 |
... |
| 2476 |
MIPS KVM_REG_MIPS_R31 64 |
| 2477 |
MIPS KVM_REG_MIPS_HI 64 |
| 2478 |
MIPS KVM_REG_MIPS_LO 64 |
| 2479 |
MIPS KVM_REG_MIPS_PC 64 |
| 2480 |
MIPS KVM_REG_MIPS_CP0_INDEX 32 |
| 2481 |
MIPS KVM_REG_MIPS_CP0_ENTRYLO0 64 |
| 2482 |
MIPS KVM_REG_MIPS_CP0_ENTRYLO1 64 |
| 2483 |
MIPS KVM_REG_MIPS_CP0_CONTEXT 64 |
| 2484 |
MIPS KVM_REG_MIPS_CP0_CONTEXTCONFIG 32 |
| 2485 |
MIPS KVM_REG_MIPS_CP0_USERLOCAL 64 |
| 2486 |
MIPS KVM_REG_MIPS_CP0_XCONTEXTCONFIG 64 |
| 2487 |
MIPS KVM_REG_MIPS_CP0_PAGEMASK 32 |
| 2488 |
MIPS KVM_REG_MIPS_CP0_PAGEGRAIN 32 |
| 2489 |
MIPS KVM_REG_MIPS_CP0_SEGCTL0 64 |
| 2490 |
MIPS KVM_REG_MIPS_CP0_SEGCTL1 64 |
| 2491 |
MIPS KVM_REG_MIPS_CP0_SEGCTL2 64 |
| 2492 |
MIPS KVM_REG_MIPS_CP0_PWBASE 64 |
| 2493 |
MIPS KVM_REG_MIPS_CP0_PWFIELD 64 |
| 2494 |
MIPS KVM_REG_MIPS_CP0_PWSIZE 64 |
| 2495 |
MIPS KVM_REG_MIPS_CP0_WIRED 32 |
| 2496 |
MIPS KVM_REG_MIPS_CP0_PWCTL 32 |
| 2497 |
MIPS KVM_REG_MIPS_CP0_HWRENA 32 |
| 2498 |
MIPS KVM_REG_MIPS_CP0_BADVADDR 64 |
| 2499 |
MIPS KVM_REG_MIPS_CP0_BADINSTR 32 |
| 2500 |
MIPS KVM_REG_MIPS_CP0_BADINSTRP 32 |
| 2501 |
MIPS KVM_REG_MIPS_CP0_COUNT 32 |
| 2502 |
MIPS KVM_REG_MIPS_CP0_ENTRYHI 64 |
| 2503 |
MIPS KVM_REG_MIPS_CP0_COMPARE 32 |
| 2504 |
MIPS KVM_REG_MIPS_CP0_STATUS 32 |
| 2505 |
MIPS KVM_REG_MIPS_CP0_INTCTL 32 |
| 2506 |
MIPS KVM_REG_MIPS_CP0_CAUSE 32 |
| 2507 |
MIPS KVM_REG_MIPS_CP0_EPC 64 |
| 2508 |
MIPS KVM_REG_MIPS_CP0_PRID 32 |
| 2509 |
MIPS KVM_REG_MIPS_CP0_EBASE 64 |
| 2510 |
MIPS KVM_REG_MIPS_CP0_CONFIG 32 |
| 2511 |
MIPS KVM_REG_MIPS_CP0_CONFIG1 32 |
| 2512 |
MIPS KVM_REG_MIPS_CP0_CONFIG2 32 |
| 2513 |
MIPS KVM_REG_MIPS_CP0_CONFIG3 32 |
| 2514 |
MIPS KVM_REG_MIPS_CP0_CONFIG4 32 |
| 2515 |
MIPS KVM_REG_MIPS_CP0_CONFIG5 32 |
| 2516 |
MIPS KVM_REG_MIPS_CP0_CONFIG7 32 |
| 2517 |
MIPS KVM_REG_MIPS_CP0_XCONTEXT 64 |
| 2518 |
MIPS KVM_REG_MIPS_CP0_ERROREPC 64 |
| 2519 |
MIPS KVM_REG_MIPS_CP0_KSCRATCH1 64 |
| 2520 |
MIPS KVM_REG_MIPS_CP0_KSCRATCH2 64 |
| 2521 |
MIPS KVM_REG_MIPS_CP0_KSCRATCH3 64 |
| 2522 |
MIPS KVM_REG_MIPS_CP0_KSCRATCH4 64 |
| 2523 |
MIPS KVM_REG_MIPS_CP0_KSCRATCH5 64 |
| 2524 |
MIPS KVM_REG_MIPS_CP0_KSCRATCH6 64 |
| 2525 |
MIPS KVM_REG_MIPS_CP0_MAAR(0..63) 64 |
| 2526 |
MIPS KVM_REG_MIPS_COUNT_CTL 64 |
| 2527 |
MIPS KVM_REG_MIPS_COUNT_RESUME 64 |
| 2528 |
MIPS KVM_REG_MIPS_COUNT_HZ 64 |
| 2529 |
MIPS KVM_REG_MIPS_FPR_32(0..31) 32 |
| 2530 |
MIPS KVM_REG_MIPS_FPR_64(0..31) 64 |
| 2531 |
MIPS KVM_REG_MIPS_VEC_128(0..31) 128 |
| 2532 |
MIPS KVM_REG_MIPS_FCR_IR 32 |
| 2533 |
MIPS KVM_REG_MIPS_FCR_CSR 32 |
| 2534 |
MIPS KVM_REG_MIPS_MSA_IR 32 |
| 2535 |
MIPS KVM_REG_MIPS_MSA_CSR 32 |
| 2536 |
======= =============================== ============ |
| 2537 |
|
| 2538 |
ARM registers are mapped using the lower 32 bits. The upper 16 of that |
| 2539 |
is the register group type, or coprocessor number: |
| 2540 |
|
| 2541 |
ARM core registers have the following id bit patterns:: |
| 2542 |
|
| 2543 |
0x4020 0000 0010 <index into the kvm_regs struct:16> |
| 2544 |
|
| 2545 |
ARM 32-bit CP15 registers have the following id bit patterns:: |
| 2546 |
|
| 2547 |
0x4020 0000 000F <zero:1> <crn:4> <crm:4> <opc1:4> <opc2:3> |
| 2548 |
|
| 2549 |
ARM 64-bit CP15 registers have the following id bit patterns:: |
| 2550 |
|
| 2551 |
0x4030 0000 000F <zero:1> <zero:4> <crm:4> <opc1:4> <zero:3> |
| 2552 |
|
| 2553 |
ARM CCSIDR registers are demultiplexed by CSSELR value:: |
| 2554 |
|
| 2555 |
0x4020 0000 0011 00 <csselr:8> |
| 2556 |
|
| 2557 |
ARM 32-bit VFP control registers have the following id bit patterns:: |
| 2558 |
|
| 2559 |
0x4020 0000 0012 1 <regno:12> |
| 2560 |
|
| 2561 |
ARM 64-bit FP registers have the following id bit patterns:: |
| 2562 |
|
| 2563 |
0x4030 0000 0012 0 <regno:12> |
| 2564 |
|
| 2565 |
ARM firmware pseudo-registers have the following bit pattern:: |
| 2566 |
|
| 2567 |
0x4030 0000 0014 <regno:16> |
| 2568 |
|
| 2569 |
|
| 2570 |
arm64 registers are mapped using the lower 32 bits. The upper 16 of |
| 2571 |
that is the register group type, or coprocessor number: |
| 2572 |
|
| 2573 |
arm64 core/FP-SIMD registers have the following id bit patterns. Note |
| 2574 |
that the size of the access is variable, as the kvm_regs structure |
| 2575 |
contains elements ranging from 32 to 128 bits. The index is a 32bit |
| 2576 |
value in the kvm_regs structure seen as a 32bit array:: |
| 2577 |
|
| 2578 |
0x60x0 0000 0010 <index into the kvm_regs struct:16> |
| 2579 |
|
| 2580 |
Specifically: |
| 2581 |
|
| 2582 |
======================= ========= ===== ======================================= |
| 2583 |
Encoding Register Bits kvm_regs member |
| 2584 |
======================= ========= ===== ======================================= |
| 2585 |
0x6030 0000 0010 0000 X0 64 regs.regs[0] |
| 2586 |
0x6030 0000 0010 0002 X1 64 regs.regs[1] |
| 2587 |
... |
| 2588 |
0x6030 0000 0010 003c X30 64 regs.regs[30] |
| 2589 |
0x6030 0000 0010 003e SP 64 regs.sp |
| 2590 |
0x6030 0000 0010 0040 PC 64 regs.pc |
| 2591 |
0x6030 0000 0010 0042 PSTATE 64 regs.pstate |
| 2592 |
0x6030 0000 0010 0044 SP_EL1 64 sp_el1 |
| 2593 |
0x6030 0000 0010 0046 ELR_EL1 64 elr_el1 |
| 2594 |
0x6030 0000 0010 0048 SPSR_EL1 64 spsr[KVM_SPSR_EL1] (alias SPSR_SVC) |
| 2595 |
0x6030 0000 0010 004a SPSR_ABT 64 spsr[KVM_SPSR_ABT] |
| 2596 |
0x6030 0000 0010 004c SPSR_UND 64 spsr[KVM_SPSR_UND] |
| 2597 |
0x6030 0000 0010 004e SPSR_IRQ 64 spsr[KVM_SPSR_IRQ] |
| 2598 |
0x6030 0000 0010 0050 SPSR_FIQ 64 spsr[KVM_SPSR_FIQ] |
| 2599 |
0x6040 0000 0010 0054 V0 128 fp_regs.vregs[0] [1]_ |
| 2600 |
0x6040 0000 0010 0058 V1 128 fp_regs.vregs[1] [1]_ |
| 2601 |
... |
| 2602 |
0x6040 0000 0010 00d0 V31 128 fp_regs.vregs[31] [1]_ |
| 2603 |
0x6020 0000 0010 00d4 FPSR 32 fp_regs.fpsr |
| 2604 |
0x6020 0000 0010 00d5 FPCR 32 fp_regs.fpcr |
| 2605 |
======================= ========= ===== ======================================= |
| 2606 |
|
| 2607 |
.. [1] These encodings are not accepted for SVE-enabled vcpus. See |
| 2608 |
:ref:`KVM_ARM_VCPU_INIT`. |
| 2609 |
|
| 2610 |
The equivalent register content can be accessed via bits [127:0] of |
| 2611 |
the corresponding SVE Zn registers instead for vcpus that have SVE |
| 2612 |
enabled (see below). |
| 2613 |
|
| 2614 |
arm64 CCSIDR registers are demultiplexed by CSSELR value:: |
| 2615 |
|
| 2616 |
0x6020 0000 0011 00 <csselr:8> |
| 2617 |
|
| 2618 |
arm64 system registers have the following id bit patterns:: |
| 2619 |
|
| 2620 |
0x6030 0000 0013 <op0:2> <op1:3> <crn:4> <crm:4> <op2:3> |
| 2621 |
|
| 2622 |
.. warning:: |
| 2623 |
|
| 2624 |
Two system register IDs do not follow the specified pattern. These |
| 2625 |
are KVM_REG_ARM_TIMER_CVAL and KVM_REG_ARM_TIMER_CNT, which map to |
| 2626 |
system registers CNTV_CVAL_EL0 and CNTVCT_EL0 respectively. These |
| 2627 |
two had their values accidentally swapped, which means TIMER_CVAL is |
| 2628 |
derived from the register encoding for CNTVCT_EL0 and TIMER_CNT is |
| 2629 |
derived from the register encoding for CNTV_CVAL_EL0. As this is |
| 2630 |
API, it must remain this way. |
| 2631 |
|
| 2632 |
arm64 firmware pseudo-registers have the following bit pattern:: |
| 2633 |
|
| 2634 |
0x6030 0000 0014 <regno:16> |
| 2635 |
|
| 2636 |
arm64 SVE registers have the following bit patterns:: |
| 2637 |
|
| 2638 |
0x6080 0000 0015 00 <n:5> <slice:5> Zn bits[2048*slice + 2047 : 2048*slice] |
| 2639 |
0x6050 0000 0015 04 <n:4> <slice:5> Pn bits[256*slice + 255 : 256*slice] |
| 2640 |
0x6050 0000 0015 060 <slice:5> FFR bits[256*slice + 255 : 256*slice] |
| 2641 |
0x6060 0000 0015 ffff KVM_REG_ARM64_SVE_VLS pseudo-register |
| 2642 |
|
| 2643 |
Access to register IDs where 2048 * slice >= 128 * max_vq will fail with |
| 2644 |
ENOENT. max_vq is the vcpu's maximum supported vector length in 128-bit |
| 2645 |
quadwords: see [2]_ below. |
| 2646 |
|
| 2647 |
These registers are only accessible on vcpus for which SVE is enabled. |
| 2648 |
See KVM_ARM_VCPU_INIT for details. |
| 2649 |
|
| 2650 |
In addition, except for KVM_REG_ARM64_SVE_VLS, these registers are not |
| 2651 |
accessible until the vcpu's SVE configuration has been finalized |
| 2652 |
using KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE). See KVM_ARM_VCPU_INIT |
| 2653 |
and KVM_ARM_VCPU_FINALIZE for more information about this procedure. |
| 2654 |
|
| 2655 |
KVM_REG_ARM64_SVE_VLS is a pseudo-register that allows the set of vector |
| 2656 |
lengths supported by the vcpu to be discovered and configured by |
| 2657 |
userspace. When transferred to or from user memory via KVM_GET_ONE_REG |
| 2658 |
or KVM_SET_ONE_REG, the value of this register is of type |
| 2659 |
__u64[KVM_ARM64_SVE_VLS_WORDS], and encodes the set of vector lengths as |
| 2660 |
follows:: |
| 2661 |
|
| 2662 |
__u64 vector_lengths[KVM_ARM64_SVE_VLS_WORDS]; |
| 2663 |
|
| 2664 |
if (vq >= SVE_VQ_MIN && vq <= SVE_VQ_MAX && |
| 2665 |
((vector_lengths[(vq - KVM_ARM64_SVE_VQ_MIN) / 64] >> |
| 2666 |
((vq - KVM_ARM64_SVE_VQ_MIN) % 64)) & 1)) |
| 2667 |
/* Vector length vq * 16 bytes supported */ |
| 2668 |
else |
| 2669 |
/* Vector length vq * 16 bytes not supported */ |
| 2670 |
|
| 2671 |
.. [2] The maximum value vq for which the above condition is true is |
| 2672 |
max_vq. This is the maximum vector length available to the guest on |
| 2673 |
this vcpu, and determines which register slices are visible through |
| 2674 |
this ioctl interface. |
| 2675 |
|
| 2676 |
(See Documentation/arch/arm64/sve.rst for an explanation of the "vq" |
| 2677 |
nomenclature.) |
| 2678 |
|
| 2679 |
KVM_REG_ARM64_SVE_VLS is only accessible after KVM_ARM_VCPU_INIT. |
| 2680 |
KVM_ARM_VCPU_INIT initialises it to the best set of vector lengths that |
| 2681 |
the host supports. |
| 2682 |
|
| 2683 |
Userspace may subsequently modify it if desired until the vcpu's SVE |
| 2684 |
configuration is finalized using KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE). |
| 2685 |
|
| 2686 |
Apart from simply removing all vector lengths from the host set that |
| 2687 |
exceed some value, support for arbitrarily chosen sets of vector lengths |
| 2688 |
is hardware-dependent and may not be available. Attempting to configure |
| 2689 |
an invalid set of vector lengths via KVM_SET_ONE_REG will fail with |
| 2690 |
EINVAL. |
| 2691 |
|
| 2692 |
After the vcpu's SVE configuration is finalized, further attempts to |
| 2693 |
write this register will fail with EPERM. |
| 2694 |
|
| 2695 |
arm64 bitmap feature firmware pseudo-registers have the following bit pattern:: |
| 2696 |
|
| 2697 |
0x6030 0000 0016 <regno:16> |
| 2698 |
|
| 2699 |
The bitmap feature firmware registers exposes the hypercall services that |
| 2700 |
are available for userspace to configure. The set bits corresponds to the |
| 2701 |
services that are available for the guests to access. By default, KVM |
| 2702 |
sets all the supported bits during VM initialization. The userspace can |
| 2703 |
discover the available services via KVM_GET_ONE_REG, and write back the |
| 2704 |
bitmap corresponding to the features that it wishes guests to see via |
| 2705 |
KVM_SET_ONE_REG. |
| 2706 |
|
| 2707 |
Note: These registers are immutable once any of the vCPUs of the VM has |
| 2708 |
run at least once. A KVM_SET_ONE_REG in such a scenario will return |
| 2709 |
a -EBUSY to userspace. |
| 2710 |
|
| 2711 |
(See Documentation/virt/kvm/arm/hypercalls.rst for more details.) |
| 2712 |
|
| 2713 |
|
| 2714 |
MIPS registers are mapped using the lower 32 bits. The upper 16 of that is |
| 2715 |
the register group type: |
| 2716 |
|
| 2717 |
MIPS core registers (see above) have the following id bit patterns:: |
| 2718 |
|
| 2719 |
0x7030 0000 0000 <reg:16> |
| 2720 |
|
| 2721 |
MIPS CP0 registers (see KVM_REG_MIPS_CP0_* above) have the following id bit |
| 2722 |
patterns depending on whether they're 32-bit or 64-bit registers:: |
| 2723 |
|
| 2724 |
0x7020 0000 0001 00 <reg:5> <sel:3> (32-bit) |
| 2725 |
0x7030 0000 0001 00 <reg:5> <sel:3> (64-bit) |
| 2726 |
|
| 2727 |
Note: KVM_REG_MIPS_CP0_ENTRYLO0 and KVM_REG_MIPS_CP0_ENTRYLO1 are the MIPS64 |
| 2728 |
versions of the EntryLo registers regardless of the word size of the host |
| 2729 |
hardware, host kernel, guest, and whether XPA is present in the guest, i.e. |
| 2730 |
with the RI and XI bits (if they exist) in bits 63 and 62 respectively, and |
| 2731 |
the PFNX field starting at bit 30. |
| 2732 |
|
| 2733 |
MIPS MAARs (see KVM_REG_MIPS_CP0_MAAR(*) above) have the following id bit |
| 2734 |
patterns:: |
| 2735 |
|
| 2736 |
0x7030 0000 0001 01 <reg:8> |
| 2737 |
|
| 2738 |
MIPS KVM control registers (see above) have the following id bit patterns:: |
| 2739 |
|
| 2740 |
0x7030 0000 0002 <reg:16> |
| 2741 |
|
| 2742 |
MIPS FPU registers (see KVM_REG_MIPS_FPR_{32,64}() above) have the following |
| 2743 |
id bit patterns depending on the size of the register being accessed. They are |
| 2744 |
always accessed according to the current guest FPU mode (Status.FR and |
| 2745 |
Config5.FRE), i.e. as the guest would see them, and they become unpredictable |
| 2746 |
if the guest FPU mode is changed. MIPS SIMD Architecture (MSA) vector |
| 2747 |
registers (see KVM_REG_MIPS_VEC_128() above) have similar patterns as they |
| 2748 |
overlap the FPU registers:: |
| 2749 |
|
| 2750 |
0x7020 0000 0003 00 <0:3> <reg:5> (32-bit FPU registers) |
| 2751 |
0x7030 0000 0003 00 <0:3> <reg:5> (64-bit FPU registers) |
| 2752 |
0x7040 0000 0003 00 <0:3> <reg:5> (128-bit MSA vector registers) |
| 2753 |
|
| 2754 |
MIPS FPU control registers (see KVM_REG_MIPS_FCR_{IR,CSR} above) have the |
| 2755 |
following id bit patterns:: |
| 2756 |
|
| 2757 |
0x7020 0000 0003 01 <0:3> <reg:5> |
| 2758 |
|
| 2759 |
MIPS MSA control registers (see KVM_REG_MIPS_MSA_{IR,CSR} above) have the |
| 2760 |
following id bit patterns:: |
| 2761 |
|
| 2762 |
0x7020 0000 0003 02 <0:3> <reg:5> |
| 2763 |
|
| 2764 |
RISC-V registers are mapped using the lower 32 bits. The upper 8 bits of |
| 2765 |
that is the register group type. |
| 2766 |
|
| 2767 |
RISC-V config registers are meant for configuring a Guest VCPU and it has |
| 2768 |
the following id bit patterns:: |
| 2769 |
|
| 2770 |
0x8020 0000 01 <index into the kvm_riscv_config struct:24> (32bit Host) |
| 2771 |
0x8030 0000 01 <index into the kvm_riscv_config struct:24> (64bit Host) |
| 2772 |
|
| 2773 |
Following are the RISC-V config registers: |
| 2774 |
|
| 2775 |
======================= ========= ============================================= |
| 2776 |
Encoding Register Description |
| 2777 |
======================= ========= ============================================= |
| 2778 |
0x80x0 0000 0100 0000 isa ISA feature bitmap of Guest VCPU |
| 2779 |
======================= ========= ============================================= |
| 2780 |
|
| 2781 |
The isa config register can be read anytime but can only be written before |
| 2782 |
a Guest VCPU runs. It will have ISA feature bits matching underlying host |
| 2783 |
set by default. |
| 2784 |
|
| 2785 |
RISC-V core registers represent the general execution state of a Guest VCPU |
| 2786 |
and it has the following id bit patterns:: |
| 2787 |
|
| 2788 |
0x8020 0000 02 <index into the kvm_riscv_core struct:24> (32bit Host) |
| 2789 |
0x8030 0000 02 <index into the kvm_riscv_core struct:24> (64bit Host) |
| 2790 |
|
| 2791 |
Following are the RISC-V core registers: |
| 2792 |
|
| 2793 |
======================= ========= ============================================= |
| 2794 |
Encoding Register Description |
| 2795 |
======================= ========= ============================================= |
| 2796 |
0x80x0 0000 0200 0000 regs.pc Program counter |
| 2797 |
0x80x0 0000 0200 0001 regs.ra Return address |
| 2798 |
0x80x0 0000 0200 0002 regs.sp Stack pointer |
| 2799 |
0x80x0 0000 0200 0003 regs.gp Global pointer |
| 2800 |
0x80x0 0000 0200 0004 regs.tp Task pointer |
| 2801 |
0x80x0 0000 0200 0005 regs.t0 Caller saved register 0 |
| 2802 |
0x80x0 0000 0200 0006 regs.t1 Caller saved register 1 |
| 2803 |
0x80x0 0000 0200 0007 regs.t2 Caller saved register 2 |
| 2804 |
0x80x0 0000 0200 0008 regs.s0 Callee saved register 0 |
| 2805 |
0x80x0 0000 0200 0009 regs.s1 Callee saved register 1 |
| 2806 |
0x80x0 0000 0200 000a regs.a0 Function argument (or return value) 0 |
| 2807 |
0x80x0 0000 0200 000b regs.a1 Function argument (or return value) 1 |
| 2808 |
0x80x0 0000 0200 000c regs.a2 Function argument 2 |
| 2809 |
0x80x0 0000 0200 000d regs.a3 Function argument 3 |
| 2810 |
0x80x0 0000 0200 000e regs.a4 Function argument 4 |
| 2811 |
0x80x0 0000 0200 000f regs.a5 Function argument 5 |
| 2812 |
0x80x0 0000 0200 0010 regs.a6 Function argument 6 |
| 2813 |
0x80x0 0000 0200 0011 regs.a7 Function argument 7 |
| 2814 |
0x80x0 0000 0200 0012 regs.s2 Callee saved register 2 |
| 2815 |
0x80x0 0000 0200 0013 regs.s3 Callee saved register 3 |
| 2816 |
0x80x0 0000 0200 0014 regs.s4 Callee saved register 4 |
| 2817 |
0x80x0 0000 0200 0015 regs.s5 Callee saved register 5 |
| 2818 |
0x80x0 0000 0200 0016 regs.s6 Callee saved register 6 |
| 2819 |
0x80x0 0000 0200 0017 regs.s7 Callee saved register 7 |
| 2820 |
0x80x0 0000 0200 0018 regs.s8 Callee saved register 8 |
| 2821 |
0x80x0 0000 0200 0019 regs.s9 Callee saved register 9 |
| 2822 |
0x80x0 0000 0200 001a regs.s10 Callee saved register 10 |
| 2823 |
0x80x0 0000 0200 001b regs.s11 Callee saved register 11 |
| 2824 |
0x80x0 0000 0200 001c regs.t3 Caller saved register 3 |
| 2825 |
0x80x0 0000 0200 001d regs.t4 Caller saved register 4 |
| 2826 |
0x80x0 0000 0200 001e regs.t5 Caller saved register 5 |
| 2827 |
0x80x0 0000 0200 001f regs.t6 Caller saved register 6 |
| 2828 |
0x80x0 0000 0200 0020 mode Privilege mode (1 = S-mode or 0 = U-mode) |
| 2829 |
======================= ========= ============================================= |
| 2830 |
|
| 2831 |
RISC-V csr registers represent the supervisor mode control/status registers |
| 2832 |
of a Guest VCPU and it has the following id bit patterns:: |
| 2833 |
|
| 2834 |
0x8020 0000 03 <index into the kvm_riscv_csr struct:24> (32bit Host) |
| 2835 |
0x8030 0000 03 <index into the kvm_riscv_csr struct:24> (64bit Host) |
| 2836 |
|
| 2837 |
Following are the RISC-V csr registers: |
| 2838 |
|
| 2839 |
======================= ========= ============================================= |
| 2840 |
Encoding Register Description |
| 2841 |
======================= ========= ============================================= |
| 2842 |
0x80x0 0000 0300 0000 sstatus Supervisor status |
| 2843 |
0x80x0 0000 0300 0001 sie Supervisor interrupt enable |
| 2844 |
0x80x0 0000 0300 0002 stvec Supervisor trap vector base |
| 2845 |
0x80x0 0000 0300 0003 sscratch Supervisor scratch register |
| 2846 |
0x80x0 0000 0300 0004 sepc Supervisor exception program counter |
| 2847 |
0x80x0 0000 0300 0005 scause Supervisor trap cause |
| 2848 |
0x80x0 0000 0300 0006 stval Supervisor bad address or instruction |
| 2849 |
0x80x0 0000 0300 0007 sip Supervisor interrupt pending |
| 2850 |
0x80x0 0000 0300 0008 satp Supervisor address translation and protection |
| 2851 |
======================= ========= ============================================= |
| 2852 |
|
| 2853 |
RISC-V timer registers represent the timer state of a Guest VCPU and it has |
| 2854 |
the following id bit patterns:: |
| 2855 |
|
| 2856 |
0x8030 0000 04 <index into the kvm_riscv_timer struct:24> |
| 2857 |
|
| 2858 |
Following are the RISC-V timer registers: |
| 2859 |
|
| 2860 |
======================= ========= ============================================= |
| 2861 |
Encoding Register Description |
| 2862 |
======================= ========= ============================================= |
| 2863 |
0x8030 0000 0400 0000 frequency Time base frequency (read-only) |
| 2864 |
0x8030 0000 0400 0001 time Time value visible to Guest |
| 2865 |
0x8030 0000 0400 0002 compare Time compare programmed by Guest |
| 2866 |
0x8030 0000 0400 0003 state Time compare state (1 = ON or 0 = OFF) |
| 2867 |
======================= ========= ============================================= |
| 2868 |
|
| 2869 |
RISC-V F-extension registers represent the single precision floating point |
| 2870 |
state of a Guest VCPU and it has the following id bit patterns:: |
| 2871 |
|
| 2872 |
0x8020 0000 05 <index into the __riscv_f_ext_state struct:24> |
| 2873 |
|
| 2874 |
Following are the RISC-V F-extension registers: |
| 2875 |
|
| 2876 |
======================= ========= ============================================= |
| 2877 |
Encoding Register Description |
| 2878 |
======================= ========= ============================================= |
| 2879 |
0x8020 0000 0500 0000 f[0] Floating point register 0 |
| 2880 |
... |
| 2881 |
0x8020 0000 0500 001f f[31] Floating point register 31 |
| 2882 |
0x8020 0000 0500 0020 fcsr Floating point control and status register |
| 2883 |
======================= ========= ============================================= |
| 2884 |
|
| 2885 |
RISC-V D-extension registers represent the double precision floating point |
| 2886 |
state of a Guest VCPU and it has the following id bit patterns:: |
| 2887 |
|
| 2888 |
0x8020 0000 06 <index into the __riscv_d_ext_state struct:24> (fcsr) |
| 2889 |
0x8030 0000 06 <index into the __riscv_d_ext_state struct:24> (non-fcsr) |
| 2890 |
|
| 2891 |
Following are the RISC-V D-extension registers: |
| 2892 |
|
| 2893 |
======================= ========= ============================================= |
| 2894 |
Encoding Register Description |
| 2895 |
======================= ========= ============================================= |
| 2896 |
0x8030 0000 0600 0000 f[0] Floating point register 0 |
| 2897 |
... |
| 2898 |
0x8030 0000 0600 001f f[31] Floating point register 31 |
| 2899 |
0x8020 0000 0600 0020 fcsr Floating point control and status register |
| 2900 |
======================= ========= ============================================= |
| 2901 |
|
| 2902 |
LoongArch registers are mapped using the lower 32 bits. The upper 16 bits of |
| 2903 |
that is the register group type. |
| 2904 |
|
| 2905 |
LoongArch csr registers are used to control guest cpu or get status of guest |
| 2906 |
cpu, and they have the following id bit patterns:: |
| 2907 |
|
| 2908 |
0x9030 0000 0001 00 <reg:5> <sel:3> (64-bit) |
| 2909 |
|
| 2910 |
LoongArch KVM control registers are used to implement some new defined functions |
| 2911 |
such as set vcpu counter or reset vcpu, and they have the following id bit patterns:: |
| 2912 |
|
| 2913 |
0x9030 0000 0002 <reg:16> |
| 2914 |
|
| 2915 |
x86 MSR registers have the following id bit patterns:: |
| 2916 |
0x2030 0002 <msr number:32> |
| 2917 |
|
| 2918 |
Following are the KVM-defined registers for x86: |
| 2919 |
|
| 2920 |
======================= ========= ============================================= |
| 2921 |
Encoding Register Description |
| 2922 |
======================= ========= ============================================= |
| 2923 |
0x2030 0003 0000 0000 SSP Shadow Stack Pointer |
| 2924 |
======================= ========= ============================================= |
| 2925 |
|
| 2926 |
4.69 KVM_GET_ONE_REG |
| 2927 |
-------------------- |
| 2928 |
|
| 2929 |
:Capability: KVM_CAP_ONE_REG |
| 2930 |
:Architectures: all |
| 2931 |
:Type: vcpu ioctl |
| 2932 |
:Parameters: struct kvm_one_reg (in and out) |
| 2933 |
:Returns: 0 on success, negative value on failure |
| 2934 |
|
| 2935 |
Errors include: |
| 2936 |
|
| 2937 |
======== ============================================================ |
| 2938 |
ENOENT no such register |
| 2939 |
EINVAL invalid register ID, or no such register or used with VMs in |
| 2940 |
protected virtualization mode on s390 |
| 2941 |
EPERM (arm64) register access not allowed before vcpu finalization |
| 2942 |
======== ============================================================ |
| 2943 |
|
| 2944 |
(These error codes are indicative only: do not rely on a specific error |
| 2945 |
code being returned in a specific situation.) |
| 2946 |
|
| 2947 |
This ioctl allows to receive the value of a single register implemented |
| 2948 |
in a vcpu. The register to read is indicated by the "id" field of the |
| 2949 |
kvm_one_reg struct passed in. On success, the register value can be found |
| 2950 |
at the memory location pointed to by "addr". |
| 2951 |
|
| 2952 |
The list of registers accessible using this interface is identical to the |
| 2953 |
list in 4.68. |
| 2954 |
|
| 2955 |
|
| 2956 |
4.70 KVM_KVMCLOCK_CTRL |
| 2957 |
---------------------- |
| 2958 |
|
| 2959 |
:Capability: KVM_CAP_KVMCLOCK_CTRL |
| 2960 |
:Architectures: Any that implement pvclocks (currently x86 only) |
| 2961 |
:Type: vcpu ioctl |
| 2962 |
:Parameters: None |
| 2963 |
:Returns: 0 on success, -1 on error |
| 2964 |
|
| 2965 |
This ioctl sets a flag accessible to the guest indicating that the specified |
| 2966 |
vCPU has been paused by the host userspace. |
| 2967 |
|
| 2968 |
The host will set a flag in the pvclock structure that is checked from the |
| 2969 |
soft lockup watchdog. The flag is part of the pvclock structure that is |
| 2970 |
shared between guest and host, specifically the second bit of the flags |
| 2971 |
field of the pvclock_vcpu_time_info structure. It will be set exclusively by |
| 2972 |
the host and read/cleared exclusively by the guest. The guest operation of |
| 2973 |
checking and clearing the flag must be an atomic operation so |
| 2974 |
load-link/store-conditional, or equivalent must be used. There are two cases |
| 2975 |
where the guest will clear the flag: when the soft lockup watchdog timer resets |
| 2976 |
itself or when a soft lockup is detected. This ioctl can be called any time |
| 2977 |
after pausing the vcpu, but before it is resumed. |
| 2978 |
|
| 2979 |
|
| 2980 |
4.71 KVM_SIGNAL_MSI |
| 2981 |
------------------- |
| 2982 |
|
| 2983 |
:Capability: KVM_CAP_SIGNAL_MSI |
| 2984 |
:Architectures: x86 arm64 |
| 2985 |
:Type: vm ioctl |
| 2986 |
:Parameters: struct kvm_msi (in) |
| 2987 |
:Returns: >0 on delivery, 0 if guest blocked the MSI, and -1 on error |
| 2988 |
|
| 2989 |
Directly inject a MSI message. Only valid with in-kernel irqchip that handles |
| 2990 |
MSI messages. |
| 2991 |
|
| 2992 |
:: |
| 2993 |
|
| 2994 |
struct kvm_msi { |
| 2995 |
__u32 address_lo; |
| 2996 |
__u32 address_hi; |
| 2997 |
__u32 data; |
| 2998 |
__u32 flags; |
| 2999 |
__u32 devid; |
| 3000 |
__u8 pad[12]; |
| 3001 |
}; |
| 3002 |
|
| 3003 |
flags: |
| 3004 |
KVM_MSI_VALID_DEVID: devid contains a valid value. The per-VM |
| 3005 |
KVM_CAP_MSI_DEVID capability advertises the requirement to provide |
| 3006 |
the device ID. If this capability is not available, userspace |
| 3007 |
should never set the KVM_MSI_VALID_DEVID flag as the ioctl might fail. |
| 3008 |
|
| 3009 |
If KVM_MSI_VALID_DEVID is set, devid contains a unique device identifier |
| 3010 |
for the device that wrote the MSI message. For PCI, this is usually a |
| 3011 |
BDF identifier in the lower 16 bits. |
| 3012 |
|
| 3013 |
On x86, address_hi is ignored unless the KVM_X2APIC_API_USE_32BIT_IDS |
| 3014 |
feature of KVM_CAP_X2APIC_API capability is enabled. If it is enabled, |
| 3015 |
address_hi bits 31-8 provide bits 31-8 of the destination id. Bits 7-0 of |
| 3016 |
address_hi must be zero. |
| 3017 |
|
| 3018 |
|
| 3019 |
4.71 KVM_CREATE_PIT2 |
| 3020 |
-------------------- |
| 3021 |
|
| 3022 |
:Capability: KVM_CAP_PIT2 |
| 3023 |
:Architectures: x86 |
| 3024 |
:Type: vm ioctl |
| 3025 |
:Parameters: struct kvm_pit_config (in) |
| 3026 |
:Returns: 0 on success, -1 on error |
| 3027 |
|
| 3028 |
Creates an in-kernel device model for the i8254 PIT. This call is only valid |
| 3029 |
after enabling in-kernel irqchip support via KVM_CREATE_IRQCHIP. The following |
| 3030 |
parameters have to be passed:: |
| 3031 |
|
| 3032 |
struct kvm_pit_config { |
| 3033 |
__u32 flags; |
| 3034 |
__u32 pad[15]; |
| 3035 |
}; |
| 3036 |
|
| 3037 |
Valid flags are:: |
| 3038 |
|
| 3039 |
#define KVM_PIT_SPEAKER_DUMMY 1 /* emulate speaker port stub */ |
| 3040 |
|
| 3041 |
PIT timer interrupts may use a per-VM kernel thread for injection. If it |
| 3042 |
exists, this thread will have a name of the following pattern:: |
| 3043 |
|
| 3044 |
kvm-pit/<owner-process-pid> |
| 3045 |
|
| 3046 |
When running a guest with elevated priorities, the scheduling parameters of |
| 3047 |
this thread may have to be adjusted accordingly. |
| 3048 |
|
| 3049 |
This IOCTL replaces the obsolete KVM_CREATE_PIT. |
| 3050 |
|
| 3051 |
|
| 3052 |
4.72 KVM_GET_PIT2 |
| 3053 |
----------------- |
| 3054 |
|
| 3055 |
:Capability: KVM_CAP_PIT_STATE2 |
| 3056 |
:Architectures: x86 |
| 3057 |
:Type: vm ioctl |
| 3058 |
:Parameters: struct kvm_pit_state2 (out) |
| 3059 |
:Returns: 0 on success, -1 on error |
| 3060 |
|
| 3061 |
Retrieves the state of the in-kernel PIT model. Only valid after |
| 3062 |
KVM_CREATE_PIT2. The state is returned in the following structure:: |
| 3063 |
|
| 3064 |
struct kvm_pit_state2 { |
| 3065 |
struct kvm_pit_channel_state channels[3]; |
| 3066 |
__u32 flags; |
| 3067 |
__u32 reserved[9]; |
| 3068 |
}; |
| 3069 |
|
| 3070 |
Valid flags are:: |
| 3071 |
|
| 3072 |
/* disable PIT in HPET legacy mode */ |
| 3073 |
#define KVM_PIT_FLAGS_HPET_LEGACY 0x00000001 |
| 3074 |
/* speaker port data bit enabled */ |
| 3075 |
#define KVM_PIT_FLAGS_SPEAKER_DATA_ON 0x00000002 |
| 3076 |
|
| 3077 |
This IOCTL replaces the obsolete KVM_GET_PIT. |
| 3078 |
|
| 3079 |
|
| 3080 |
4.73 KVM_SET_PIT2 |
| 3081 |
----------------- |
| 3082 |
|
| 3083 |
:Capability: KVM_CAP_PIT_STATE2 |
| 3084 |
:Architectures: x86 |
| 3085 |
:Type: vm ioctl |
| 3086 |
:Parameters: struct kvm_pit_state2 (in) |
| 3087 |
:Returns: 0 on success, -1 on error |
| 3088 |
|
| 3089 |
Sets the state of the in-kernel PIT model. Only valid after KVM_CREATE_PIT2. |
| 3090 |
See KVM_GET_PIT2 for details on struct kvm_pit_state2. |
| 3091 |
|
| 3092 |
.. Tip:: |
| 3093 |
``KVM_SET_PIT2`` strictly adheres to the spec of Intel 8254 PIT. For example, |
| 3094 |
a ``count`` value of 0 in ``struct kvm_pit_channel_state`` is interpreted as |
| 3095 |
65536, which is the maximum count value. Refer to `Intel 8254 programmable |
| 3096 |
interval timer <https://www.scs.stanford.edu/10wi-cs140/pintos/specs/8254.pdf>`_. |
| 3097 |
|
| 3098 |
This IOCTL replaces the obsolete KVM_SET_PIT. |
| 3099 |
|
| 3100 |
|
| 3101 |
4.74 KVM_PPC_GET_SMMU_INFO |
| 3102 |
-------------------------- |
| 3103 |
|
| 3104 |
:Capability: KVM_CAP_PPC_GET_SMMU_INFO |
| 3105 |
:Architectures: powerpc |
| 3106 |
:Type: vm ioctl |
| 3107 |
:Parameters: None |
| 3108 |
:Returns: 0 on success, -1 on error |
| 3109 |
|
| 3110 |
This populates and returns a structure describing the features of |
| 3111 |
the "Server" class MMU emulation supported by KVM. |
| 3112 |
This can in turn be used by userspace to generate the appropriate |
| 3113 |
device-tree properties for the guest operating system. |
| 3114 |
|
| 3115 |
The structure contains some global information, followed by an |
| 3116 |
array of supported segment page sizes:: |
| 3117 |
|
| 3118 |
struct kvm_ppc_smmu_info { |
| 3119 |
__u64 flags; |
| 3120 |
__u32 slb_size; |
| 3121 |
__u32 pad; |
| 3122 |
struct kvm_ppc_one_seg_page_size sps[KVM_PPC_PAGE_SIZES_MAX_SZ]; |
| 3123 |
}; |
| 3124 |
|
| 3125 |
The supported flags are: |
| 3126 |
|
| 3127 |
- KVM_PPC_PAGE_SIZES_REAL: |
| 3128 |
When that flag is set, guest page sizes must "fit" the backing |
| 3129 |
store page sizes. When not set, any page size in the list can |
| 3130 |
be used regardless of how they are backed by userspace. |
| 3131 |
|
| 3132 |
- KVM_PPC_1T_SEGMENTS |
| 3133 |
The emulated MMU supports 1T segments in addition to the |
| 3134 |
standard 256M ones. |
| 3135 |
|
| 3136 |
- KVM_PPC_NO_HASH |
| 3137 |
This flag indicates that HPT guests are not supported by KVM, |
| 3138 |
thus all guests must use radix MMU mode. |
| 3139 |
|
| 3140 |
The "slb_size" field indicates how many SLB entries are supported |
| 3141 |
|
| 3142 |
The "sps" array contains 8 entries indicating the supported base |
| 3143 |
page sizes for a segment in increasing order. Each entry is defined |
| 3144 |
as follow:: |
| 3145 |
|
| 3146 |
struct kvm_ppc_one_seg_page_size { |
| 3147 |
__u32 page_shift; /* Base page shift of segment (or 0) */ |
| 3148 |
__u32 slb_enc; /* SLB encoding for BookS */ |
| 3149 |
struct kvm_ppc_one_page_size enc[KVM_PPC_PAGE_SIZES_MAX_SZ]; |
| 3150 |
}; |
| 3151 |
|
| 3152 |
An entry with a "page_shift" of 0 is unused. Because the array is |
| 3153 |
organized in increasing order, a lookup can stop when encountering |
| 3154 |
such an entry. |
| 3155 |
|
| 3156 |
The "slb_enc" field provides the encoding to use in the SLB for the |
| 3157 |
page size. The bits are in positions such as the value can directly |
| 3158 |
be OR'ed into the "vsid" argument of the slbmte instruction. |
| 3159 |
|
| 3160 |
The "enc" array is a list which for each of those segment base page |
| 3161 |
size provides the list of supported actual page sizes (which can be |
| 3162 |
only larger or equal to the base page size), along with the |
| 3163 |
corresponding encoding in the hash PTE. Similarly, the array is |
| 3164 |
8 entries sorted by increasing sizes and an entry with a "0" shift |
| 3165 |
is an empty entry and a terminator:: |
| 3166 |
|
| 3167 |
struct kvm_ppc_one_page_size { |
| 3168 |
__u32 page_shift; /* Page shift (or 0) */ |
| 3169 |
__u32 pte_enc; /* Encoding in the HPTE (>>12) */ |
| 3170 |
}; |
| 3171 |
|
| 3172 |
The "pte_enc" field provides a value that can OR'ed into the hash |
| 3173 |
PTE's RPN field (ie, it needs to be shifted left by 12 to OR it |
| 3174 |
into the hash PTE second double word). |
| 3175 |
|
| 3176 |
4.75 KVM_IRQFD |
| 3177 |
-------------- |
| 3178 |
|
| 3179 |
:Capability: KVM_CAP_IRQFD |
| 3180 |
:Architectures: x86 s390 arm64 |
| 3181 |
:Type: vm ioctl |
| 3182 |
:Parameters: struct kvm_irqfd (in) |
| 3183 |
:Returns: 0 on success, -1 on error |
| 3184 |
|
| 3185 |
Allows setting an eventfd to directly trigger a guest interrupt. |
| 3186 |
kvm_irqfd.fd specifies the file descriptor to use as the eventfd and |
| 3187 |
kvm_irqfd.gsi specifies the irqchip pin toggled by this event. When |
| 3188 |
an event is triggered on the eventfd, an interrupt is injected into |
| 3189 |
the guest using the specified gsi pin. The irqfd is removed using |
| 3190 |
the KVM_IRQFD_FLAG_DEASSIGN flag, specifying both kvm_irqfd.fd |
| 3191 |
and kvm_irqfd.gsi. |
| 3192 |
|
| 3193 |
With KVM_CAP_IRQFD_RESAMPLE, KVM_IRQFD supports a de-assert and notify |
| 3194 |
mechanism allowing emulation of level-triggered, irqfd-based |
| 3195 |
interrupts. When KVM_IRQFD_FLAG_RESAMPLE is set the user must pass an |
| 3196 |
additional eventfd in the kvm_irqfd.resamplefd field. When operating |
| 3197 |
in resample mode, posting of an interrupt through kvm_irq.fd asserts |
| 3198 |
the specified gsi in the irqchip. When the irqchip is resampled, such |
| 3199 |
as from an EOI, the gsi is de-asserted and the user is notified via |
| 3200 |
kvm_irqfd.resamplefd. It is the user's responsibility to re-queue |
| 3201 |
the interrupt if the device making use of it still requires service. |
| 3202 |
Note that closing the resamplefd is not sufficient to disable the |
| 3203 |
irqfd. The KVM_IRQFD_FLAG_RESAMPLE is only necessary on assignment |
| 3204 |
and need not be specified with KVM_IRQFD_FLAG_DEASSIGN. |
| 3205 |
|
| 3206 |
On arm64, gsi routing being supported, the following can happen: |
| 3207 |
|
| 3208 |
- in case no routing entry is associated to this gsi, injection fails |
| 3209 |
- in case the gsi is associated to an irqchip routing entry, |
| 3210 |
irqchip.pin + 32 corresponds to the injected SPI ID. |
| 3211 |
- in case the gsi is associated to an MSI routing entry, the MSI |
| 3212 |
message and device ID are translated into an LPI (support restricted |
| 3213 |
to GICv3 ITS in-kernel emulation). |
| 3214 |
|
| 3215 |
4.76 KVM_PPC_ALLOCATE_HTAB |
| 3216 |
-------------------------- |
| 3217 |
|
| 3218 |
:Capability: KVM_CAP_PPC_ALLOC_HTAB |
| 3219 |
:Architectures: powerpc |
| 3220 |
:Type: vm ioctl |
| 3221 |
:Parameters: Pointer to u32 containing hash table order (in/out) |
| 3222 |
:Returns: 0 on success, -1 on error |
| 3223 |
|
| 3224 |
This requests the host kernel to allocate an MMU hash table for a |
| 3225 |
guest using the PAPR paravirtualization interface. This only does |
| 3226 |
anything if the kernel is configured to use the Book 3S HV style of |
| 3227 |
virtualization. Otherwise the capability doesn't exist and the ioctl |
| 3228 |
returns an ENOTTY error. The rest of this description assumes Book 3S |
| 3229 |
HV. |
| 3230 |
|
| 3231 |
There must be no vcpus running when this ioctl is called; if there |
| 3232 |
are, it will do nothing and return an EBUSY error. |
| 3233 |
|
| 3234 |
The parameter is a pointer to a 32-bit unsigned integer variable |
| 3235 |
containing the order (log base 2) of the desired size of the hash |
| 3236 |
table, which must be between 18 and 46. On successful return from the |
| 3237 |
ioctl, the value will not be changed by the kernel. |
| 3238 |
|
| 3239 |
If no hash table has been allocated when any vcpu is asked to run |
| 3240 |
(with the KVM_RUN ioctl), the host kernel will allocate a |
| 3241 |
default-sized hash table (16 MB). |
| 3242 |
|
| 3243 |
If this ioctl is called when a hash table has already been allocated, |
| 3244 |
with a different order from the existing hash table, the existing hash |
| 3245 |
table will be freed and a new one allocated. If this is ioctl is |
| 3246 |
called when a hash table has already been allocated of the same order |
| 3247 |
as specified, the kernel will clear out the existing hash table (zero |
| 3248 |
all HPTEs). In either case, if the guest is using the virtualized |
| 3249 |
real-mode area (VRMA) facility, the kernel will re-create the VMRA |
| 3250 |
HPTEs on the next KVM_RUN of any vcpu. |
| 3251 |
|
| 3252 |
4.77 KVM_S390_INTERRUPT |
| 3253 |
----------------------- |
| 3254 |
|
| 3255 |
:Capability: basic |
| 3256 |
:Architectures: s390 |
| 3257 |
:Type: vm ioctl, vcpu ioctl |
| 3258 |
:Parameters: struct kvm_s390_interrupt (in) |
| 3259 |
:Returns: 0 on success, -1 on error |
| 3260 |
|
| 3261 |
Allows to inject an interrupt to the guest. Interrupts can be floating |
| 3262 |
(vm ioctl) or per cpu (vcpu ioctl), depending on the interrupt type. |
| 3263 |
|
| 3264 |
Interrupt parameters are passed via kvm_s390_interrupt:: |
| 3265 |
|
| 3266 |
struct kvm_s390_interrupt { |
| 3267 |
__u32 type; |
| 3268 |
__u32 parm; |
| 3269 |
__u64 parm64; |
| 3270 |
}; |
| 3271 |
|
| 3272 |
type can be one of the following: |
| 3273 |
|
| 3274 |
KVM_S390_SIGP_STOP (vcpu) |
| 3275 |
- sigp stop; optional flags in parm |
| 3276 |
KVM_S390_PROGRAM_INT (vcpu) |
| 3277 |
- program check; code in parm |
| 3278 |
KVM_S390_SIGP_SET_PREFIX (vcpu) |
| 3279 |
- sigp set prefix; prefix address in parm |
| 3280 |
KVM_S390_RESTART (vcpu) |
| 3281 |
- restart |
| 3282 |
KVM_S390_INT_CLOCK_COMP (vcpu) |
| 3283 |
- clock comparator interrupt |
| 3284 |
KVM_S390_INT_CPU_TIMER (vcpu) |
| 3285 |
- CPU timer interrupt |
| 3286 |
KVM_S390_INT_VIRTIO (vm) |
| 3287 |
- virtio external interrupt; external interrupt |
| 3288 |
parameters in parm and parm64 |
| 3289 |
KVM_S390_INT_SERVICE (vm) |
| 3290 |
- sclp external interrupt; sclp parameter in parm |
| 3291 |
KVM_S390_INT_EMERGENCY (vcpu) |
| 3292 |
- sigp emergency; source cpu in parm |
| 3293 |
KVM_S390_INT_EXTERNAL_CALL (vcpu) |
| 3294 |
- sigp external call; source cpu in parm |
| 3295 |
KVM_S390_INT_IO(ai,cssid,ssid,schid) (vm) |
| 3296 |
- compound value to indicate an |
| 3297 |
I/O interrupt (ai - adapter interrupt; cssid,ssid,schid - subchannel); |
| 3298 |
I/O interruption parameters in parm (subchannel) and parm64 (intparm, |
| 3299 |
interruption subclass) |
| 3300 |
KVM_S390_MCHK (vm, vcpu) |
| 3301 |
- machine check interrupt; cr 14 bits in parm, machine check interrupt |
| 3302 |
code in parm64 (note that machine checks needing further payload are not |
| 3303 |
supported by this ioctl) |
| 3304 |
|
| 3305 |
This is an asynchronous vcpu ioctl and can be invoked from any thread. |
| 3306 |
|
| 3307 |
4.78 KVM_PPC_GET_HTAB_FD |
| 3308 |
------------------------ |
| 3309 |
|
| 3310 |
:Capability: KVM_CAP_PPC_HTAB_FD |
| 3311 |
:Architectures: powerpc |
| 3312 |
:Type: vm ioctl |
| 3313 |
:Parameters: Pointer to struct kvm_get_htab_fd (in) |
| 3314 |
:Returns: file descriptor number (>= 0) on success, -1 on error |
| 3315 |
|
| 3316 |
This returns a file descriptor that can be used either to read out the |
| 3317 |
entries in the guest's hashed page table (HPT), or to write entries to |
| 3318 |
initialize the HPT. The returned fd can only be written to if the |
| 3319 |
KVM_GET_HTAB_WRITE bit is set in the flags field of the argument, and |
| 3320 |
can only be read if that bit is clear. The argument struct looks like |
| 3321 |
this:: |
| 3322 |
|
| 3323 |
/* For KVM_PPC_GET_HTAB_FD */ |
| 3324 |
struct kvm_get_htab_fd { |
| 3325 |
__u64 flags; |
| 3326 |
__u64 start_index; |
| 3327 |
__u64 reserved[2]; |
| 3328 |
}; |
| 3329 |
|
| 3330 |
/* Values for kvm_get_htab_fd.flags */ |
| 3331 |
#define KVM_GET_HTAB_BOLTED_ONLY ((__u64)0x1) |
| 3332 |
#define KVM_GET_HTAB_WRITE ((__u64)0x2) |
| 3333 |
|
| 3334 |
The 'start_index' field gives the index in the HPT of the entry at |
| 3335 |
which to start reading. It is ignored when writing. |
| 3336 |
|
| 3337 |
Reads on the fd will initially supply information about all |
| 3338 |
"interesting" HPT entries. Interesting entries are those with the |
| 3339 |
bolted bit set, if the KVM_GET_HTAB_BOLTED_ONLY bit is set, otherwise |
| 3340 |
all entries. When the end of the HPT is reached, the read() will |
| 3341 |
return. If read() is called again on the fd, it will start again from |
| 3342 |
the beginning of the HPT, but will only return HPT entries that have |
| 3343 |
changed since they were last read. |
| 3344 |
|
| 3345 |
Data read or written is structured as a header (8 bytes) followed by a |
| 3346 |
series of valid HPT entries (16 bytes) each. The header indicates how |
| 3347 |
many valid HPT entries there are and how many invalid entries follow |
| 3348 |
the valid entries. The invalid entries are not represented explicitly |
| 3349 |
in the stream. The header format is:: |
| 3350 |
|
| 3351 |
struct kvm_get_htab_header { |
| 3352 |
__u32 index; |
| 3353 |
__u16 n_valid; |
| 3354 |
__u16 n_invalid; |
| 3355 |
}; |
| 3356 |
|
| 3357 |
Writes to the fd create HPT entries starting at the index given in the |
| 3358 |
header; first 'n_valid' valid entries with contents from the data |
| 3359 |
written, then 'n_invalid' invalid entries, invalidating any previously |
| 3360 |
valid entries found. |
| 3361 |
|
| 3362 |
4.79 KVM_CREATE_DEVICE |
| 3363 |
---------------------- |
| 3364 |
|
| 3365 |
:Capability: KVM_CAP_DEVICE_CTRL |
| 3366 |
:Architectures: all |
| 3367 |
:Type: vm ioctl |
| 3368 |
:Parameters: struct kvm_create_device (in/out) |
| 3369 |
:Returns: 0 on success, -1 on error |
| 3370 |
|
| 3371 |
Errors: |
| 3372 |
|
| 3373 |
====== ======================================================= |
| 3374 |
ENODEV The device type is unknown or unsupported |
| 3375 |
EEXIST Device already created, and this type of device may not |
| 3376 |
be instantiated multiple times |
| 3377 |
====== ======================================================= |
| 3378 |
|
| 3379 |
Other error conditions may be defined by individual device types or |
| 3380 |
have their standard meanings. |
| 3381 |
|
| 3382 |
Creates an emulated device in the kernel. The file descriptor returned |
| 3383 |
in fd can be used with KVM_SET/GET/HAS_DEVICE_ATTR. |
| 3384 |
|
| 3385 |
If the KVM_CREATE_DEVICE_TEST flag is set, only test whether the |
| 3386 |
device type is supported (not necessarily whether it can be created |
| 3387 |
in the current vm). |
| 3388 |
|
| 3389 |
Individual devices should not define flags. Attributes should be used |
| 3390 |
for specifying any behavior that is not implied by the device type |
| 3391 |
number. |
| 3392 |
|
| 3393 |
:: |
| 3394 |
|
| 3395 |
struct kvm_create_device { |
| 3396 |
__u32 type; /* in: KVM_DEV_TYPE_xxx */ |
| 3397 |
__u32 fd; /* out: device handle */ |
| 3398 |
__u32 flags; /* in: KVM_CREATE_DEVICE_xxx */ |
| 3399 |
}; |
| 3400 |
|
| 3401 |
4.80 KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR |
| 3402 |
-------------------------------------------- |
| 3403 |
|
| 3404 |
:Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device, |
| 3405 |
KVM_CAP_VCPU_ATTRIBUTES for vcpu device |
| 3406 |
KVM_CAP_SYS_ATTRIBUTES for system (/dev/kvm) device (no set) |
| 3407 |
:Architectures: x86, arm64, s390 |
| 3408 |
:Type: device ioctl, vm ioctl, vcpu ioctl |
| 3409 |
:Parameters: struct kvm_device_attr |
| 3410 |
:Returns: 0 on success, -1 on error |
| 3411 |
|
| 3412 |
Errors: |
| 3413 |
|
| 3414 |
===== ============================================================= |
| 3415 |
ENXIO The group or attribute is unknown/unsupported for this device |
| 3416 |
or hardware support is missing. |
| 3417 |
EPERM The attribute cannot (currently) be accessed this way |
| 3418 |
(e.g. read-only attribute, or attribute that only makes |
| 3419 |
sense when the device is in a different state) |
| 3420 |
===== ============================================================= |
| 3421 |
|
| 3422 |
Other error conditions may be defined by individual device types. |
| 3423 |
|
| 3424 |
Gets/sets a specified piece of device configuration and/or state. The |
| 3425 |
semantics are device-specific. See individual device documentation in |
| 3426 |
the "devices" directory. As with ONE_REG, the size of the data |
| 3427 |
transferred is defined by the particular attribute. |
| 3428 |
|
| 3429 |
:: |
| 3430 |
|
| 3431 |
struct kvm_device_attr { |
| 3432 |
__u32 flags; /* no flags currently defined */ |
| 3433 |
__u32 group; /* device-defined */ |
| 3434 |
__u64 attr; /* group-defined */ |
| 3435 |
__u64 addr; /* userspace address of attr data */ |
| 3436 |
}; |
| 3437 |
|
| 3438 |
4.81 KVM_HAS_DEVICE_ATTR |
| 3439 |
------------------------ |
| 3440 |
|
| 3441 |
:Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device, |
| 3442 |
KVM_CAP_VCPU_ATTRIBUTES for vcpu device |
| 3443 |
KVM_CAP_SYS_ATTRIBUTES for system (/dev/kvm) device |
| 3444 |
:Type: device ioctl, vm ioctl, vcpu ioctl |
| 3445 |
:Parameters: struct kvm_device_attr |
| 3446 |
:Returns: 0 on success, -1 on error |
| 3447 |
|
| 3448 |
Errors: |
| 3449 |
|
| 3450 |
===== ============================================================= |
| 3451 |
ENXIO The group or attribute is unknown/unsupported for this device |
| 3452 |
or hardware support is missing. |
| 3453 |
===== ============================================================= |
| 3454 |
|
| 3455 |
Tests whether a device supports a particular attribute. A successful |
| 3456 |
return indicates the attribute is implemented. It does not necessarily |
| 3457 |
indicate that the attribute can be read or written in the device's |
| 3458 |
current state. "addr" is ignored. |
| 3459 |
|
| 3460 |
.. _KVM_ARM_VCPU_INIT: |
| 3461 |
|
| 3462 |
4.82 KVM_ARM_VCPU_INIT |
| 3463 |
---------------------- |
| 3464 |
|
| 3465 |
:Capability: basic |
| 3466 |
:Architectures: arm64 |
| 3467 |
:Type: vcpu ioctl |
| 3468 |
:Parameters: struct kvm_vcpu_init (in) |
| 3469 |
:Returns: 0 on success; -1 on error |
| 3470 |
|
| 3471 |
Errors: |
| 3472 |
|
| 3473 |
====== ================================================================= |
| 3474 |
EINVAL the target is unknown, or the combination of features is invalid. |
| 3475 |
ENOENT a features bit specified is unknown. |
| 3476 |
====== ================================================================= |
| 3477 |
|
| 3478 |
This tells KVM what type of CPU to present to the guest, and what |
| 3479 |
optional features it should have. This will cause a reset of the cpu |
| 3480 |
registers to their initial values. If this is not called, KVM_RUN will |
| 3481 |
return ENOEXEC for that vcpu. |
| 3482 |
|
| 3483 |
The initial values are defined as: |
| 3484 |
- Processor state: |
| 3485 |
* AArch64: EL1h, D, A, I and F bits set. All other bits |
| 3486 |
are cleared. |
| 3487 |
* AArch32: SVC, A, I and F bits set. All other bits are |
| 3488 |
cleared. |
| 3489 |
- General Purpose registers, including PC and SP: set to 0 |
| 3490 |
- FPSIMD/NEON registers: set to 0 |
| 3491 |
- SVE registers: set to 0 |
| 3492 |
- System registers: Reset to their architecturally defined |
| 3493 |
values as for a warm reset to EL1 (resp. SVC) or EL2 (in the |
| 3494 |
case of EL2 being enabled). |
| 3495 |
|
| 3496 |
Note that because some registers reflect machine topology, all vcpus |
| 3497 |
should be created before this ioctl is invoked. |
| 3498 |
|
| 3499 |
Userspace can call this function multiple times for a given vcpu, including |
| 3500 |
after the vcpu has been run. This will reset the vcpu to its initial |
| 3501 |
state. All calls to this function after the initial call must use the same |
| 3502 |
target and same set of feature flags, otherwise EINVAL will be returned. |
| 3503 |
|
| 3504 |
Possible features: |
| 3505 |
|
| 3506 |
- KVM_ARM_VCPU_POWER_OFF: Starts the CPU in a power-off state. |
| 3507 |
Depends on KVM_CAP_ARM_PSCI. If not set, the CPU will be powered on |
| 3508 |
and execute guest code when KVM_RUN is called. |
| 3509 |
- KVM_ARM_VCPU_EL1_32BIT: Starts the CPU in a 32bit mode. |
| 3510 |
Depends on KVM_CAP_ARM_EL1_32BIT (arm64 only). |
| 3511 |
- KVM_ARM_VCPU_PSCI_0_2: Emulate PSCI v0.2 (or a future revision |
| 3512 |
backward compatible with v0.2) for the CPU. |
| 3513 |
Depends on KVM_CAP_ARM_PSCI_0_2. |
| 3514 |
- KVM_ARM_VCPU_PMU_V3: Emulate PMUv3 for the CPU. |
| 3515 |
Depends on KVM_CAP_ARM_PMU_V3. |
| 3516 |
|
| 3517 |
- KVM_ARM_VCPU_PTRAUTH_ADDRESS: Enables Address Pointer authentication |
| 3518 |
for arm64 only. |
| 3519 |
Depends on KVM_CAP_ARM_PTRAUTH_ADDRESS. |
| 3520 |
If KVM_CAP_ARM_PTRAUTH_ADDRESS and KVM_CAP_ARM_PTRAUTH_GENERIC are |
| 3521 |
both present, then both KVM_ARM_VCPU_PTRAUTH_ADDRESS and |
| 3522 |
KVM_ARM_VCPU_PTRAUTH_GENERIC must be requested or neither must be |
| 3523 |
requested. |
| 3524 |
|
| 3525 |
- KVM_ARM_VCPU_PTRAUTH_GENERIC: Enables Generic Pointer authentication |
| 3526 |
for arm64 only. |
| 3527 |
Depends on KVM_CAP_ARM_PTRAUTH_GENERIC. |
| 3528 |
If KVM_CAP_ARM_PTRAUTH_ADDRESS and KVM_CAP_ARM_PTRAUTH_GENERIC are |
| 3529 |
both present, then both KVM_ARM_VCPU_PTRAUTH_ADDRESS and |
| 3530 |
KVM_ARM_VCPU_PTRAUTH_GENERIC must be requested or neither must be |
| 3531 |
requested. |
| 3532 |
|
| 3533 |
- KVM_ARM_VCPU_SVE: Enables SVE for the CPU (arm64 only). |
| 3534 |
Depends on KVM_CAP_ARM_SVE. |
| 3535 |
Requires KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE): |
| 3536 |
|
| 3537 |
* After KVM_ARM_VCPU_INIT: |
| 3538 |
|
| 3539 |
- KVM_REG_ARM64_SVE_VLS may be read using KVM_GET_ONE_REG: the |
| 3540 |
initial value of this pseudo-register indicates the best set of |
| 3541 |
vector lengths possible for a vcpu on this host. |
| 3542 |
|
| 3543 |
* Before KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE): |
| 3544 |
|
| 3545 |
- KVM_RUN and KVM_GET_REG_LIST are not available; |
| 3546 |
|
| 3547 |
- KVM_GET_ONE_REG and KVM_SET_ONE_REG cannot be used to access |
| 3548 |
the scalable architectural SVE registers |
| 3549 |
KVM_REG_ARM64_SVE_ZREG(), KVM_REG_ARM64_SVE_PREG() or |
| 3550 |
KVM_REG_ARM64_SVE_FFR; |
| 3551 |
|
| 3552 |
- KVM_REG_ARM64_SVE_VLS may optionally be written using |
| 3553 |
KVM_SET_ONE_REG, to modify the set of vector lengths available |
| 3554 |
for the vcpu. |
| 3555 |
|
| 3556 |
* After KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE): |
| 3557 |
|
| 3558 |
- the KVM_REG_ARM64_SVE_VLS pseudo-register is immutable, and can |
| 3559 |
no longer be written using KVM_SET_ONE_REG. |
| 3560 |
|
| 3561 |
- KVM_ARM_VCPU_HAS_EL2: Enable Nested Virtualisation support, |
| 3562 |
booting the guest from EL2 instead of EL1. |
| 3563 |
Depends on KVM_CAP_ARM_EL2. |
| 3564 |
The VM is running with HCR_EL2.E2H being RES1 (VHE) unless |
| 3565 |
KVM_ARM_VCPU_HAS_EL2_E2H0 is also set. |
| 3566 |
|
| 3567 |
- KVM_ARM_VCPU_HAS_EL2_E2H0: Restrict Nested Virtualisation |
| 3568 |
support to HCR_EL2.E2H being RES0 (non-VHE). |
| 3569 |
Depends on KVM_CAP_ARM_EL2_E2H0. |
| 3570 |
KVM_ARM_VCPU_HAS_EL2 must also be set. |
| 3571 |
|
| 3572 |
4.83 KVM_ARM_PREFERRED_TARGET |
| 3573 |
----------------------------- |
| 3574 |
|
| 3575 |
:Capability: basic |
| 3576 |
:Architectures: arm64 |
| 3577 |
:Type: vm ioctl |
| 3578 |
:Parameters: struct kvm_vcpu_init (out) |
| 3579 |
:Returns: 0 on success; -1 on error |
| 3580 |
|
| 3581 |
Errors: |
| 3582 |
|
| 3583 |
====== ========================================== |
| 3584 |
ENODEV no preferred target available for the host |
| 3585 |
====== ========================================== |
| 3586 |
|
| 3587 |
This queries KVM for preferred CPU target type which can be emulated |
| 3588 |
by KVM on underlying host. |
| 3589 |
|
| 3590 |
The ioctl returns struct kvm_vcpu_init instance containing information |
| 3591 |
about preferred CPU target type and recommended features for it. The |
| 3592 |
kvm_vcpu_init->features bitmap returned will have feature bits set if |
| 3593 |
the preferred target recommends setting these features, but this is |
| 3594 |
not mandatory. |
| 3595 |
|
| 3596 |
The information returned by this ioctl can be used to prepare an instance |
| 3597 |
of struct kvm_vcpu_init for KVM_ARM_VCPU_INIT ioctl which will result in |
| 3598 |
VCPU matching underlying host. |
| 3599 |
|
| 3600 |
|
| 3601 |
4.84 KVM_GET_REG_LIST |
| 3602 |
--------------------- |
| 3603 |
|
| 3604 |
:Capability: basic |
| 3605 |
:Architectures: arm64, mips, riscv, x86 (if KVM_CAP_ONE_REG) |
| 3606 |
:Type: vcpu ioctl |
| 3607 |
:Parameters: struct kvm_reg_list (in/out) |
| 3608 |
:Returns: 0 on success; -1 on error |
| 3609 |
|
| 3610 |
Errors: |
| 3611 |
|
| 3612 |
===== ============================================================== |
| 3613 |
E2BIG the reg index list is too big to fit in the array specified by |
| 3614 |
the user (the number required will be written into n). |
| 3615 |
===== ============================================================== |
| 3616 |
|
| 3617 |
:: |
| 3618 |
|
| 3619 |
struct kvm_reg_list { |
| 3620 |
__u64 n; /* number of registers in reg[] */ |
| 3621 |
__u64 reg[0]; |
| 3622 |
}; |
| 3623 |
|
| 3624 |
This ioctl returns the guest registers that are supported for the |
| 3625 |
KVM_GET_ONE_REG/KVM_SET_ONE_REG calls. |
| 3626 |
|
| 3627 |
Note that s390 does not support KVM_GET_REG_LIST for historical reasons |
| 3628 |
(read: nobody cared). The set of registers in kernels 4.x and newer is: |
| 3629 |
|
| 3630 |
- KVM_REG_S390_TODPR |
| 3631 |
|
| 3632 |
- KVM_REG_S390_EPOCHDIFF |
| 3633 |
|
| 3634 |
- KVM_REG_S390_CPU_TIMER |
| 3635 |
|
| 3636 |
- KVM_REG_S390_CLOCK_COMP |
| 3637 |
|
| 3638 |
- KVM_REG_S390_PFTOKEN |
| 3639 |
|
| 3640 |
- KVM_REG_S390_PFCOMPARE |
| 3641 |
|
| 3642 |
- KVM_REG_S390_PFSELECT |
| 3643 |
|
| 3644 |
- KVM_REG_S390_PP |
| 3645 |
|
| 3646 |
- KVM_REG_S390_GBEA |
| 3647 |
|
| 3648 |
Note, for x86, all MSRs enumerated by KVM_GET_MSR_INDEX_LIST are supported as |
| 3649 |
type KVM_X86_REG_TYPE_MSR, but are NOT enumerated via KVM_GET_REG_LIST. |
| 3650 |
|
| 3651 |
4.85 KVM_ARM_SET_DEVICE_ADDR (deprecated) |
| 3652 |
----------------------------------------- |
| 3653 |
|
| 3654 |
:Capability: KVM_CAP_ARM_SET_DEVICE_ADDR |
| 3655 |
:Architectures: arm64 |
| 3656 |
:Type: vm ioctl |
| 3657 |
:Parameters: struct kvm_arm_device_address (in) |
| 3658 |
:Returns: 0 on success, -1 on error |
| 3659 |
|
| 3660 |
Errors: |
| 3661 |
|
| 3662 |
====== ============================================ |
| 3663 |
ENODEV The device id is unknown |
| 3664 |
ENXIO Device not supported on current system |
| 3665 |
EEXIST Address already set |
| 3666 |
E2BIG Address outside guest physical address space |
| 3667 |
EBUSY Address overlaps with other device range |
| 3668 |
====== ============================================ |
| 3669 |
|
| 3670 |
:: |
| 3671 |
|
| 3672 |
struct kvm_arm_device_addr { |
| 3673 |
__u64 id; |
| 3674 |
__u64 addr; |
| 3675 |
}; |
| 3676 |
|
| 3677 |
Specify a device address in the guest's physical address space where guests |
| 3678 |
can access emulated or directly exposed devices, which the host kernel needs |
| 3679 |
to know about. The id field is an architecture specific identifier for a |
| 3680 |
specific device. |
| 3681 |
|
| 3682 |
arm64 divides the id field into two parts, a device id and an |
| 3683 |
address type id specific to the individual device:: |
| 3684 |
|
| 3685 |
bits: | 63 ... 32 | 31 ... 16 | 15 ... 0 | |
| 3686 |
field: | 0x00000000 | device id | addr type id | |
| 3687 |
|
| 3688 |
arm64 currently only require this when using the in-kernel GIC |
| 3689 |
support for the hardware VGIC features, using KVM_ARM_DEVICE_VGIC_V2 |
| 3690 |
as the device id. When setting the base address for the guest's |
| 3691 |
mapping of the VGIC virtual CPU and distributor interface, the ioctl |
| 3692 |
must be called after calling KVM_CREATE_IRQCHIP, but before calling |
| 3693 |
KVM_RUN on any of the VCPUs. Calling this ioctl twice for any of the |
| 3694 |
base addresses will return -EEXIST. |
| 3695 |
|
| 3696 |
Note, this IOCTL is deprecated and the more flexible SET/GET_DEVICE_ATTR API |
| 3697 |
should be used instead. |
| 3698 |
|
| 3699 |
|
| 3700 |
4.86 KVM_PPC_RTAS_DEFINE_TOKEN |
| 3701 |
------------------------------ |
| 3702 |
|
| 3703 |
:Capability: KVM_CAP_PPC_RTAS |
| 3704 |
:Architectures: ppc |
| 3705 |
:Type: vm ioctl |
| 3706 |
:Parameters: struct kvm_rtas_token_args |
| 3707 |
:Returns: 0 on success, -1 on error |
| 3708 |
|
| 3709 |
Defines a token value for a RTAS (Run Time Abstraction Services) |
| 3710 |
service in order to allow it to be handled in the kernel. The |
| 3711 |
argument struct gives the name of the service, which must be the name |
| 3712 |
of a service that has a kernel-side implementation. If the token |
| 3713 |
value is non-zero, it will be associated with that service, and |
| 3714 |
subsequent RTAS calls by the guest specifying that token will be |
| 3715 |
handled by the kernel. If the token value is 0, then any token |
| 3716 |
associated with the service will be forgotten, and subsequent RTAS |
| 3717 |
calls by the guest for that service will be passed to userspace to be |
| 3718 |
handled. |
| 3719 |
|
| 3720 |
4.87 KVM_SET_GUEST_DEBUG |
| 3721 |
------------------------ |
| 3722 |
|
| 3723 |
:Capability: KVM_CAP_SET_GUEST_DEBUG |
| 3724 |
:Architectures: x86, s390, ppc, arm64 |
| 3725 |
:Type: vcpu ioctl |
| 3726 |
:Parameters: struct kvm_guest_debug (in) |
| 3727 |
:Returns: 0 on success; -1 on error |
| 3728 |
|
| 3729 |
:: |
| 3730 |
|
| 3731 |
struct kvm_guest_debug { |
| 3732 |
__u32 control; |
| 3733 |
__u32 pad; |
| 3734 |
struct kvm_guest_debug_arch arch; |
| 3735 |
}; |
| 3736 |
|
| 3737 |
Set up the processor specific debug registers and configure vcpu for |
| 3738 |
handling guest debug events. There are two parts to the structure, the |
| 3739 |
first a control bitfield indicates the type of debug events to handle |
| 3740 |
when running. Common control bits are: |
| 3741 |
|
| 3742 |
- KVM_GUESTDBG_ENABLE: guest debugging is enabled |
| 3743 |
- KVM_GUESTDBG_SINGLESTEP: the next run should single-step |
| 3744 |
|
| 3745 |
The top 16 bits of the control field are architecture specific control |
| 3746 |
flags which can include the following: |
| 3747 |
|
| 3748 |
- KVM_GUESTDBG_USE_SW_BP: using software breakpoints [x86, arm64] |
| 3749 |
- KVM_GUESTDBG_USE_HW_BP: using hardware breakpoints [x86, s390] |
| 3750 |
- KVM_GUESTDBG_USE_HW: using hardware debug events [arm64] |
| 3751 |
- KVM_GUESTDBG_INJECT_DB: inject DB type exception [x86] |
| 3752 |
- KVM_GUESTDBG_INJECT_BP: inject BP type exception [x86] |
| 3753 |
- KVM_GUESTDBG_EXIT_PENDING: trigger an immediate guest exit [s390] |
| 3754 |
- KVM_GUESTDBG_BLOCKIRQ: avoid injecting interrupts/NMI/SMI [x86] |
| 3755 |
|
| 3756 |
For example KVM_GUESTDBG_USE_SW_BP indicates that software breakpoints |
| 3757 |
are enabled in memory so we need to ensure breakpoint exceptions are |
| 3758 |
correctly trapped and the KVM run loop exits at the breakpoint and not |
| 3759 |
running off into the normal guest vector. For KVM_GUESTDBG_USE_HW_BP |
| 3760 |
we need to ensure the guest vCPUs architecture specific registers are |
| 3761 |
updated to the correct (supplied) values. |
| 3762 |
|
| 3763 |
The second part of the structure is architecture specific and |
| 3764 |
typically contains a set of debug registers. |
| 3765 |
|
| 3766 |
For arm64 the number of debug registers is implementation defined and |
| 3767 |
can be determined by querying the KVM_CAP_GUEST_DEBUG_HW_BPS and |
| 3768 |
KVM_CAP_GUEST_DEBUG_HW_WPS capabilities which return a positive number |
| 3769 |
indicating the number of supported registers. |
| 3770 |
|
| 3771 |
For ppc, the KVM_CAP_PPC_GUEST_DEBUG_SSTEP capability indicates whether |
| 3772 |
the single-step debug event (KVM_GUESTDBG_SINGLESTEP) is supported. |
| 3773 |
|
| 3774 |
Also when supported, KVM_CAP_SET_GUEST_DEBUG2 capability indicates the |
| 3775 |
supported KVM_GUESTDBG_* bits in the control field. |
| 3776 |
|
| 3777 |
When debug events exit the main run loop with the reason |
| 3778 |
KVM_EXIT_DEBUG with the kvm_debug_exit_arch part of the kvm_run |
| 3779 |
structure containing architecture specific debug information. |
| 3780 |
|
| 3781 |
4.88 KVM_GET_EMULATED_CPUID |
| 3782 |
--------------------------- |
| 3783 |
|
| 3784 |
:Capability: KVM_CAP_EXT_EMUL_CPUID |
| 3785 |
:Architectures: x86 |
| 3786 |
:Type: system ioctl |
| 3787 |
:Parameters: struct kvm_cpuid2 (in/out) |
| 3788 |
:Returns: 0 on success, -1 on error |
| 3789 |
|
| 3790 |
:: |
| 3791 |
|
| 3792 |
struct kvm_cpuid2 { |
| 3793 |
__u32 nent; |
| 3794 |
__u32 flags; |
| 3795 |
struct kvm_cpuid_entry2 entries[0]; |
| 3796 |
}; |
| 3797 |
|
| 3798 |
The member 'flags' is used for passing flags from userspace. |
| 3799 |
|
| 3800 |
:: |
| 3801 |
|
| 3802 |
#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0) |
| 3803 |
#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1) /* deprecated */ |
| 3804 |
#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2) /* deprecated */ |
| 3805 |
|
| 3806 |
struct kvm_cpuid_entry2 { |
| 3807 |
__u32 function; |
| 3808 |
__u32 index; |
| 3809 |
__u32 flags; |
| 3810 |
__u32 eax; |
| 3811 |
__u32 ebx; |
| 3812 |
__u32 ecx; |
| 3813 |
__u32 edx; |
| 3814 |
__u32 padding[3]; |
| 3815 |
}; |
| 3816 |
|
| 3817 |
This ioctl returns x86 cpuid features which are emulated by |
| 3818 |
kvm.Userspace can use the information returned by this ioctl to query |
| 3819 |
which features are emulated by kvm instead of being present natively. |
| 3820 |
|
| 3821 |
Userspace invokes KVM_GET_EMULATED_CPUID by passing a kvm_cpuid2 |
| 3822 |
structure with the 'nent' field indicating the number of entries in |
| 3823 |
the variable-size array 'entries'. If the number of entries is too low |
| 3824 |
to describe the cpu capabilities, an error (E2BIG) is returned. If the |
| 3825 |
number is too high, the 'nent' field is adjusted and an error (ENOMEM) |
| 3826 |
is returned. If the number is just right, the 'nent' field is adjusted |
| 3827 |
to the number of valid entries in the 'entries' array, which is then |
| 3828 |
filled. |
| 3829 |
|
| 3830 |
The entries returned are the set CPUID bits of the respective features |
| 3831 |
which kvm emulates, as returned by the CPUID instruction, with unknown |
| 3832 |
or unsupported feature bits cleared. |
| 3833 |
|
| 3834 |
Features like x2apic, for example, may not be present in the host cpu |
| 3835 |
but are exposed by kvm in KVM_GET_SUPPORTED_CPUID because they can be |
| 3836 |
emulated efficiently and thus not included here. |
| 3837 |
|
| 3838 |
The fields in each entry are defined as follows: |
| 3839 |
|
| 3840 |
function: |
| 3841 |
the eax value used to obtain the entry |
| 3842 |
index: |
| 3843 |
the ecx value used to obtain the entry (for entries that are |
| 3844 |
affected by ecx) |
| 3845 |
flags: |
| 3846 |
an OR of zero or more of the following: |
| 3847 |
|
| 3848 |
KVM_CPUID_FLAG_SIGNIFCANT_INDEX: |
| 3849 |
if the index field is valid |
| 3850 |
|
| 3851 |
eax, ebx, ecx, edx: |
| 3852 |
|
| 3853 |
the values returned by the cpuid instruction for |
| 3854 |
this function/index combination |
| 3855 |
|
| 3856 |
4.89 KVM_S390_MEM_OP |
| 3857 |
-------------------- |
| 3858 |
|
| 3859 |
:Capability: KVM_CAP_S390_MEM_OP, KVM_CAP_S390_PROTECTED, KVM_CAP_S390_MEM_OP_EXTENSION |
| 3860 |
:Architectures: s390 |
| 3861 |
:Type: vm ioctl, vcpu ioctl |
| 3862 |
:Parameters: struct kvm_s390_mem_op (in) |
| 3863 |
:Returns: = 0 on success, |
| 3864 |
< 0 on generic error (e.g. -EFAULT or -ENOMEM), |
| 3865 |
16 bit program exception code if the access causes such an exception |
| 3866 |
|
| 3867 |
Read or write data from/to the VM's memory. |
| 3868 |
The KVM_CAP_S390_MEM_OP_EXTENSION capability specifies what functionality is |
| 3869 |
supported. |
| 3870 |
|
| 3871 |
Parameters are specified via the following structure:: |
| 3872 |
|
| 3873 |
struct kvm_s390_mem_op { |
| 3874 |
__u64 gaddr; /* the guest address */ |
| 3875 |
__u64 flags; /* flags */ |
| 3876 |
__u32 size; /* amount of bytes */ |
| 3877 |
__u32 op; /* type of operation */ |
| 3878 |
__u64 buf; /* buffer in userspace */ |
| 3879 |
union { |
| 3880 |
struct { |
| 3881 |
__u8 ar; /* the access register number */ |
| 3882 |
__u8 key; /* access key, ignored if flag unset */ |
| 3883 |
__u8 pad1[6]; /* ignored */ |
| 3884 |
__u64 old_addr; /* ignored if flag unset */ |
| 3885 |
}; |
| 3886 |
__u32 sida_offset; /* offset into the sida */ |
| 3887 |
__u8 reserved[32]; /* ignored */ |
| 3888 |
}; |
| 3889 |
}; |
| 3890 |
|
| 3891 |
The start address of the memory region has to be specified in the "gaddr" |
| 3892 |
field, and the length of the region in the "size" field (which must not |
| 3893 |
be 0). The maximum value for "size" can be obtained by checking the |
| 3894 |
KVM_CAP_S390_MEM_OP capability. "buf" is the buffer supplied by the |
| 3895 |
userspace application where the read data should be written to for |
| 3896 |
a read access, or where the data that should be written is stored for |
| 3897 |
a write access. The "reserved" field is meant for future extensions. |
| 3898 |
Reserved and unused values are ignored. Future extension that add members must |
| 3899 |
introduce new flags. |
| 3900 |
|
| 3901 |
The type of operation is specified in the "op" field. Flags modifying |
| 3902 |
their behavior can be set in the "flags" field. Undefined flag bits must |
| 3903 |
be set to 0. |
| 3904 |
|
| 3905 |
Possible operations are: |
| 3906 |
* ``KVM_S390_MEMOP_LOGICAL_READ`` |
| 3907 |
* ``KVM_S390_MEMOP_LOGICAL_WRITE`` |
| 3908 |
* ``KVM_S390_MEMOP_ABSOLUTE_READ`` |
| 3909 |
* ``KVM_S390_MEMOP_ABSOLUTE_WRITE`` |
| 3910 |
* ``KVM_S390_MEMOP_SIDA_READ`` |
| 3911 |
* ``KVM_S390_MEMOP_SIDA_WRITE`` |
| 3912 |
* ``KVM_S390_MEMOP_ABSOLUTE_CMPXCHG`` |
| 3913 |
|
| 3914 |
Logical read/write: |
| 3915 |
^^^^^^^^^^^^^^^^^^^ |
| 3916 |
|
| 3917 |
Access logical memory, i.e. translate the given guest address to an absolute |
| 3918 |
address given the state of the VCPU and use the absolute address as target of |
| 3919 |
the access. "ar" designates the access register number to be used; the valid |
| 3920 |
range is 0..15. |
| 3921 |
Logical accesses are permitted for the VCPU ioctl only. |
| 3922 |
Logical accesses are permitted for non-protected guests only. |
| 3923 |
|
| 3924 |
Supported flags: |
| 3925 |
* ``KVM_S390_MEMOP_F_CHECK_ONLY`` |
| 3926 |
* ``KVM_S390_MEMOP_F_INJECT_EXCEPTION`` |
| 3927 |
* ``KVM_S390_MEMOP_F_SKEY_PROTECTION`` |
| 3928 |
|
| 3929 |
The KVM_S390_MEMOP_F_CHECK_ONLY flag can be set to check whether the |
| 3930 |
corresponding memory access would cause an access exception; however, |
| 3931 |
no actual access to the data in memory at the destination is performed. |
| 3932 |
In this case, "buf" is unused and can be NULL. |
| 3933 |
|
| 3934 |
In case an access exception occurred during the access (or would occur |
| 3935 |
in case of KVM_S390_MEMOP_F_CHECK_ONLY), the ioctl returns a positive |
| 3936 |
error number indicating the type of exception. This exception is also |
| 3937 |
raised directly at the corresponding VCPU if the flag |
| 3938 |
KVM_S390_MEMOP_F_INJECT_EXCEPTION is set. |
| 3939 |
On protection exceptions, unless specified otherwise, the injected |
| 3940 |
translation-exception identifier (TEID) indicates suppression. |
| 3941 |
|
| 3942 |
If the KVM_S390_MEMOP_F_SKEY_PROTECTION flag is set, storage key |
| 3943 |
protection is also in effect and may cause exceptions if accesses are |
| 3944 |
prohibited given the access key designated by "key"; the valid range is 0..15. |
| 3945 |
KVM_S390_MEMOP_F_SKEY_PROTECTION is available if KVM_CAP_S390_MEM_OP_EXTENSION |
| 3946 |
is > 0. |
| 3947 |
Since the accessed memory may span multiple pages and those pages might have |
| 3948 |
different storage keys, it is possible that a protection exception occurs |
| 3949 |
after memory has been modified. In this case, if the exception is injected, |
| 3950 |
the TEID does not indicate suppression. |
| 3951 |
|
| 3952 |
Absolute read/write: |
| 3953 |
^^^^^^^^^^^^^^^^^^^^ |
| 3954 |
|
| 3955 |
Access absolute memory. This operation is intended to be used with the |
| 3956 |
KVM_S390_MEMOP_F_SKEY_PROTECTION flag, to allow accessing memory and performing |
| 3957 |
the checks required for storage key protection as one operation (as opposed to |
| 3958 |
user space getting the storage keys, performing the checks, and accessing |
| 3959 |
memory thereafter, which could lead to a delay between check and access). |
| 3960 |
Absolute accesses are permitted for the VM ioctl if KVM_CAP_S390_MEM_OP_EXTENSION |
| 3961 |
has the KVM_S390_MEMOP_EXTENSION_CAP_BASE bit set. |
| 3962 |
Currently absolute accesses are not permitted for VCPU ioctls. |
| 3963 |
Absolute accesses are permitted for non-protected guests only. |
| 3964 |
|
| 3965 |
Supported flags: |
| 3966 |
* ``KVM_S390_MEMOP_F_CHECK_ONLY`` |
| 3967 |
* ``KVM_S390_MEMOP_F_SKEY_PROTECTION`` |
| 3968 |
|
| 3969 |
The semantics of the flags common with logical accesses are as for logical |
| 3970 |
accesses. |
| 3971 |
|
| 3972 |
Absolute cmpxchg: |
| 3973 |
^^^^^^^^^^^^^^^^^ |
| 3974 |
|
| 3975 |
Perform cmpxchg on absolute guest memory. Intended for use with the |
| 3976 |
KVM_S390_MEMOP_F_SKEY_PROTECTION flag. |
| 3977 |
Instead of doing an unconditional write, the access occurs only if the target |
| 3978 |
location contains the value pointed to by "old_addr". |
| 3979 |
This is performed as an atomic cmpxchg with the length specified by the "size" |
| 3980 |
parameter. "size" must be a power of two up to and including 16. |
| 3981 |
If the exchange did not take place because the target value doesn't match the |
| 3982 |
old value, the value "old_addr" points to is replaced by the target value. |
| 3983 |
User space can tell if an exchange took place by checking if this replacement |
| 3984 |
occurred. The cmpxchg op is permitted for the VM ioctl if |
| 3985 |
KVM_CAP_S390_MEM_OP_EXTENSION has flag KVM_S390_MEMOP_EXTENSION_CAP_CMPXCHG set. |
| 3986 |
|
| 3987 |
Supported flags: |
| 3988 |
* ``KVM_S390_MEMOP_F_SKEY_PROTECTION`` |
| 3989 |
|
| 3990 |
SIDA read/write: |
| 3991 |
^^^^^^^^^^^^^^^^ |
| 3992 |
|
| 3993 |
Access the secure instruction data area which contains memory operands necessary |
| 3994 |
for instruction emulation for protected guests. |
| 3995 |
SIDA accesses are available if the KVM_CAP_S390_PROTECTED capability is available. |
| 3996 |
SIDA accesses are permitted for the VCPU ioctl only. |
| 3997 |
SIDA accesses are permitted for protected guests only. |
| 3998 |
|
| 3999 |
No flags are supported. |
| 4000 |
|
| 4001 |
4.90 KVM_S390_GET_SKEYS |
| 4002 |
----------------------- |
| 4003 |
|
| 4004 |
:Capability: KVM_CAP_S390_SKEYS |
| 4005 |
:Architectures: s390 |
| 4006 |
:Type: vm ioctl |
| 4007 |
:Parameters: struct kvm_s390_skeys |
| 4008 |
:Returns: 0 on success, KVM_S390_GET_SKEYS_NONE if guest is not using storage |
| 4009 |
keys, negative value on error |
| 4010 |
|
| 4011 |
This ioctl is used to get guest storage key values on the s390 |
| 4012 |
architecture. The ioctl takes parameters via the kvm_s390_skeys struct:: |
| 4013 |
|
| 4014 |
struct kvm_s390_skeys { |
| 4015 |
__u64 start_gfn; |
| 4016 |
__u64 count; |
| 4017 |
__u64 skeydata_addr; |
| 4018 |
__u32 flags; |
| 4019 |
__u32 reserved[9]; |
| 4020 |
}; |
| 4021 |
|
| 4022 |
The start_gfn field is the number of the first guest frame whose storage keys |
| 4023 |
you want to get. |
| 4024 |
|
| 4025 |
The count field is the number of consecutive frames (starting from start_gfn) |
| 4026 |
whose storage keys to get. The count field must be at least 1 and the maximum |
| 4027 |
allowed value is defined as KVM_S390_SKEYS_MAX. Values outside this range |
| 4028 |
will cause the ioctl to return -EINVAL. |
| 4029 |
|
| 4030 |
The skeydata_addr field is the address to a buffer large enough to hold count |
| 4031 |
bytes. This buffer will be filled with storage key data by the ioctl. |
| 4032 |
|
| 4033 |
4.91 KVM_S390_SET_SKEYS |
| 4034 |
----------------------- |
| 4035 |
|
| 4036 |
:Capability: KVM_CAP_S390_SKEYS |
| 4037 |
:Architectures: s390 |
| 4038 |
:Type: vm ioctl |
| 4039 |
:Parameters: struct kvm_s390_skeys |
| 4040 |
:Returns: 0 on success, negative value on error |
| 4041 |
|
| 4042 |
This ioctl is used to set guest storage key values on the s390 |
| 4043 |
architecture. The ioctl takes parameters via the kvm_s390_skeys struct. |
| 4044 |
See section on KVM_S390_GET_SKEYS for struct definition. |
| 4045 |
|
| 4046 |
The start_gfn field is the number of the first guest frame whose storage keys |
| 4047 |
you want to set. |
| 4048 |
|
| 4049 |
The count field is the number of consecutive frames (starting from start_gfn) |
| 4050 |
whose storage keys to get. The count field must be at least 1 and the maximum |
| 4051 |
allowed value is defined as KVM_S390_SKEYS_MAX. Values outside this range |
| 4052 |
will cause the ioctl to return -EINVAL. |
| 4053 |
|
| 4054 |
The skeydata_addr field is the address to a buffer containing count bytes of |
| 4055 |
storage keys. Each byte in the buffer will be set as the storage key for a |
| 4056 |
single frame starting at start_gfn for count frames. |
| 4057 |
|
| 4058 |
Note: If any architecturally invalid key value is found in the given data then |
| 4059 |
the ioctl will return -EINVAL. |
| 4060 |
|
| 4061 |
4.92 KVM_S390_IRQ |
| 4062 |
----------------- |
| 4063 |
|
| 4064 |
:Capability: KVM_CAP_S390_INJECT_IRQ |
| 4065 |
:Architectures: s390 |
| 4066 |
:Type: vcpu ioctl |
| 4067 |
:Parameters: struct kvm_s390_irq (in) |
| 4068 |
:Returns: 0 on success, -1 on error |
| 4069 |
|
| 4070 |
Errors: |
| 4071 |
|
| 4072 |
|
| 4073 |
====== ================================================================= |
| 4074 |
EINVAL interrupt type is invalid |
| 4075 |
type is KVM_S390_SIGP_STOP and flag parameter is invalid value, |
| 4076 |
type is KVM_S390_INT_EXTERNAL_CALL and code is bigger |
| 4077 |
than the maximum of VCPUs |
| 4078 |
EBUSY type is KVM_S390_SIGP_SET_PREFIX and vcpu is not stopped, |
| 4079 |
type is KVM_S390_SIGP_STOP and a stop irq is already pending, |
| 4080 |
type is KVM_S390_INT_EXTERNAL_CALL and an external call interrupt |
| 4081 |
is already pending |
| 4082 |
====== ================================================================= |
| 4083 |
|
| 4084 |
Allows to inject an interrupt to the guest. |
| 4085 |
|
| 4086 |
Using struct kvm_s390_irq as a parameter allows |
| 4087 |
to inject additional payload which is not |
| 4088 |
possible via KVM_S390_INTERRUPT. |
| 4089 |
|
| 4090 |
Interrupt parameters are passed via kvm_s390_irq:: |
| 4091 |
|
| 4092 |
struct kvm_s390_irq { |
| 4093 |
__u64 type; |
| 4094 |
union { |
| 4095 |
struct kvm_s390_io_info io; |
| 4096 |
struct kvm_s390_ext_info ext; |
| 4097 |
struct kvm_s390_pgm_info pgm; |
| 4098 |
struct kvm_s390_emerg_info emerg; |
| 4099 |
struct kvm_s390_extcall_info extcall; |
| 4100 |
struct kvm_s390_prefix_info prefix; |
| 4101 |
struct kvm_s390_stop_info stop; |
| 4102 |
struct kvm_s390_mchk_info mchk; |
| 4103 |
char reserved[64]; |
| 4104 |
} u; |
| 4105 |
}; |
| 4106 |
|
| 4107 |
type can be one of the following: |
| 4108 |
|
| 4109 |
- KVM_S390_SIGP_STOP - sigp stop; parameter in .stop |
| 4110 |
- KVM_S390_PROGRAM_INT - program check; parameters in .pgm |
| 4111 |
- KVM_S390_SIGP_SET_PREFIX - sigp set prefix; parameters in .prefix |
| 4112 |
- KVM_S390_RESTART - restart; no parameters |
| 4113 |
- KVM_S390_INT_CLOCK_COMP - clock comparator interrupt; no parameters |
| 4114 |
- KVM_S390_INT_CPU_TIMER - CPU timer interrupt; no parameters |
| 4115 |
- KVM_S390_INT_EMERGENCY - sigp emergency; parameters in .emerg |
| 4116 |
- KVM_S390_INT_EXTERNAL_CALL - sigp external call; parameters in .extcall |
| 4117 |
- KVM_S390_MCHK - machine check interrupt; parameters in .mchk |
| 4118 |
|
| 4119 |
This is an asynchronous vcpu ioctl and can be invoked from any thread. |
| 4120 |
|
| 4121 |
4.94 KVM_S390_GET_IRQ_STATE |
| 4122 |
--------------------------- |
| 4123 |
|
| 4124 |
:Capability: KVM_CAP_S390_IRQ_STATE |
| 4125 |
:Architectures: s390 |
| 4126 |
:Type: vcpu ioctl |
| 4127 |
:Parameters: struct kvm_s390_irq_state (out) |
| 4128 |
:Returns: >= number of bytes copied into buffer, |
| 4129 |
-EINVAL if buffer size is 0, |
| 4130 |
-ENOBUFS if buffer size is too small to fit all pending interrupts, |
| 4131 |
-EFAULT if the buffer address was invalid |
| 4132 |
|
| 4133 |
This ioctl allows userspace to retrieve the complete state of all currently |
| 4134 |
pending interrupts in a single buffer. Use cases include migration |
| 4135 |
and introspection. The parameter structure contains the address of a |
| 4136 |
userspace buffer and its length:: |
| 4137 |
|
| 4138 |
struct kvm_s390_irq_state { |
| 4139 |
__u64 buf; |
| 4140 |
__u32 flags; /* will stay unused for compatibility reasons */ |
| 4141 |
__u32 len; |
| 4142 |
__u32 reserved[4]; /* will stay unused for compatibility reasons */ |
| 4143 |
}; |
| 4144 |
|
| 4145 |
Userspace passes in the above struct and for each pending interrupt a |
| 4146 |
struct kvm_s390_irq is copied to the provided buffer. |
| 4147 |
|
| 4148 |
The structure contains a flags and a reserved field for future extensions. As |
| 4149 |
the kernel never checked for flags == 0 and QEMU never pre-zeroed flags and |
| 4150 |
reserved, these fields can not be used in the future without breaking |
| 4151 |
compatibility. |
| 4152 |
|
| 4153 |
If -ENOBUFS is returned the buffer provided was too small and userspace |
| 4154 |
may retry with a bigger buffer. |
| 4155 |
|
| 4156 |
4.95 KVM_S390_SET_IRQ_STATE |
| 4157 |
--------------------------- |
| 4158 |
|
| 4159 |
:Capability: KVM_CAP_S390_IRQ_STATE |
| 4160 |
:Architectures: s390 |
| 4161 |
:Type: vcpu ioctl |
| 4162 |
:Parameters: struct kvm_s390_irq_state (in) |
| 4163 |
:Returns: 0 on success, |
| 4164 |
-EFAULT if the buffer address was invalid, |
| 4165 |
-EINVAL for an invalid buffer length (see below), |
| 4166 |
-EBUSY if there were already interrupts pending, |
| 4167 |
errors occurring when actually injecting the |
| 4168 |
interrupt. See KVM_S390_IRQ. |
| 4169 |
|
| 4170 |
This ioctl allows userspace to set the complete state of all cpu-local |
| 4171 |
interrupts currently pending for the vcpu. It is intended for restoring |
| 4172 |
interrupt state after a migration. The input parameter is a userspace buffer |
| 4173 |
containing a struct kvm_s390_irq_state:: |
| 4174 |
|
| 4175 |
struct kvm_s390_irq_state { |
| 4176 |
__u64 buf; |
| 4177 |
__u32 flags; /* will stay unused for compatibility reasons */ |
| 4178 |
__u32 len; |
| 4179 |
__u32 reserved[4]; /* will stay unused for compatibility reasons */ |
| 4180 |
}; |
| 4181 |
|
| 4182 |
The restrictions for flags and reserved apply as well. |
| 4183 |
(see KVM_S390_GET_IRQ_STATE) |
| 4184 |
|
| 4185 |
The userspace memory referenced by buf contains a struct kvm_s390_irq |
| 4186 |
for each interrupt to be injected into the guest. |
| 4187 |
If one of the interrupts could not be injected for some reason the |
| 4188 |
ioctl aborts. |
| 4189 |
|
| 4190 |
len must be a multiple of sizeof(struct kvm_s390_irq). It must be > 0 |
| 4191 |
and it must not exceed (max_vcpus + 32) * sizeof(struct kvm_s390_irq), |
| 4192 |
which is the maximum number of possibly pending cpu-local interrupts. |
| 4193 |
|
| 4194 |
4.96 KVM_SMI |
| 4195 |
------------ |
| 4196 |
|
| 4197 |
:Capability: KVM_CAP_X86_SMM |
| 4198 |
:Architectures: x86 |
| 4199 |
:Type: vcpu ioctl |
| 4200 |
:Parameters: none |
| 4201 |
:Returns: 0 on success, -1 on error |
| 4202 |
|
| 4203 |
Queues an SMI on the thread's vcpu. |
| 4204 |
|
| 4205 |
4.97 KVM_X86_SET_MSR_FILTER |
| 4206 |
---------------------------- |
| 4207 |
|
| 4208 |
:Capability: KVM_CAP_X86_MSR_FILTER |
| 4209 |
:Architectures: x86 |
| 4210 |
:Type: vm ioctl |
| 4211 |
:Parameters: struct kvm_msr_filter |
| 4212 |
:Returns: 0 on success, < 0 on error |
| 4213 |
|
| 4214 |
:: |
| 4215 |
|
| 4216 |
struct kvm_msr_filter_range { |
| 4217 |
#define KVM_MSR_FILTER_READ (1 << 0) |
| 4218 |
#define KVM_MSR_FILTER_WRITE (1 << 1) |
| 4219 |
__u32 flags; |
| 4220 |
__u32 nmsrs; /* number of msrs in bitmap */ |
| 4221 |
__u32 base; /* MSR index the bitmap starts at */ |
| 4222 |
__u8 *bitmap; /* a 1 bit allows the operations in flags, 0 denies */ |
| 4223 |
}; |
| 4224 |
|
| 4225 |
#define KVM_MSR_FILTER_MAX_RANGES 16 |
| 4226 |
struct kvm_msr_filter { |
| 4227 |
#define KVM_MSR_FILTER_DEFAULT_ALLOW (0 << 0) |
| 4228 |
#define KVM_MSR_FILTER_DEFAULT_DENY (1 << 0) |
| 4229 |
__u32 flags; |
| 4230 |
struct kvm_msr_filter_range ranges[KVM_MSR_FILTER_MAX_RANGES]; |
| 4231 |
}; |
| 4232 |
|
| 4233 |
flags values for ``struct kvm_msr_filter_range``: |
| 4234 |
|
| 4235 |
``KVM_MSR_FILTER_READ`` |
| 4236 |
|
| 4237 |
Filter read accesses to MSRs using the given bitmap. A 0 in the bitmap |
| 4238 |
indicates that read accesses should be denied, while a 1 indicates that |
| 4239 |
a read for a particular MSR should be allowed regardless of the default |
| 4240 |
filter action. |
| 4241 |
|
| 4242 |
``KVM_MSR_FILTER_WRITE`` |
| 4243 |
|
| 4244 |
Filter write accesses to MSRs using the given bitmap. A 0 in the bitmap |
| 4245 |
indicates that write accesses should be denied, while a 1 indicates that |
| 4246 |
a write for a particular MSR should be allowed regardless of the default |
| 4247 |
filter action. |
| 4248 |
|
| 4249 |
flags values for ``struct kvm_msr_filter``: |
| 4250 |
|
| 4251 |
``KVM_MSR_FILTER_DEFAULT_ALLOW`` |
| 4252 |
|
| 4253 |
If no filter range matches an MSR index that is getting accessed, KVM will |
| 4254 |
allow accesses to all MSRs by default. |
| 4255 |
|
| 4256 |
``KVM_MSR_FILTER_DEFAULT_DENY`` |
| 4257 |
|
| 4258 |
If no filter range matches an MSR index that is getting accessed, KVM will |
| 4259 |
deny accesses to all MSRs by default. |
| 4260 |
|
| 4261 |
This ioctl allows userspace to define up to 16 bitmaps of MSR ranges to deny |
| 4262 |
guest MSR accesses that would normally be allowed by KVM. If an MSR is not |
| 4263 |
covered by a specific range, the "default" filtering behavior applies. Each |
| 4264 |
bitmap range covers MSRs from [base .. base+nmsrs). |
| 4265 |
|
| 4266 |
If an MSR access is denied by userspace, the resulting KVM behavior depends on |
| 4267 |
whether or not KVM_CAP_X86_USER_SPACE_MSR's KVM_MSR_EXIT_REASON_FILTER is |
| 4268 |
enabled. If KVM_MSR_EXIT_REASON_FILTER is enabled, KVM will exit to userspace |
| 4269 |
on denied accesses, i.e. userspace effectively intercepts the MSR access. If |
| 4270 |
KVM_MSR_EXIT_REASON_FILTER is not enabled, KVM will inject a #GP into the guest |
| 4271 |
on denied accesses. Note, if an MSR access is denied during emulation of MSR |
| 4272 |
load/stores during VMX transitions, KVM ignores KVM_MSR_EXIT_REASON_FILTER. |
| 4273 |
See the below warning for full details. |
| 4274 |
|
| 4275 |
If an MSR access is allowed by userspace, KVM will emulate and/or virtualize |
| 4276 |
the access in accordance with the vCPU model. Note, KVM may still ultimately |
| 4277 |
inject a #GP if an access is allowed by userspace, e.g. if KVM doesn't support |
| 4278 |
the MSR, or to follow architectural behavior for the MSR. |
| 4279 |
|
| 4280 |
By default, KVM operates in KVM_MSR_FILTER_DEFAULT_ALLOW mode with no MSR range |
| 4281 |
filters. |
| 4282 |
|
| 4283 |
Calling this ioctl with an empty set of ranges (all nmsrs == 0) disables MSR |
| 4284 |
filtering. In that mode, ``KVM_MSR_FILTER_DEFAULT_DENY`` is invalid and causes |
| 4285 |
an error. |
| 4286 |
|
| 4287 |
.. warning:: |
| 4288 |
MSR accesses that are side effects of instruction execution (emulated or |
| 4289 |
native) are not filtered as hardware does not honor MSR bitmaps outside of |
| 4290 |
RDMSR and WRMSR, and KVM mimics that behavior when emulating instructions |
| 4291 |
to avoid pointless divergence from hardware. E.g. RDPID reads MSR_TSC_AUX, |
| 4292 |
SYSENTER reads the SYSENTER MSRs, etc. |
| 4293 |
|
| 4294 |
MSRs that are loaded/stored via dedicated VMCS fields are not filtered as |
| 4295 |
part of VM-Enter/VM-Exit emulation. |
| 4296 |
|
| 4297 |
MSRs that are loaded/store via VMX's load/store lists _are_ filtered as part |
| 4298 |
of VM-Enter/VM-Exit emulation. If an MSR access is denied on VM-Enter, KVM |
| 4299 |
synthesizes a consistency check VM-Exit(EXIT_REASON_MSR_LOAD_FAIL). If an |
| 4300 |
MSR access is denied on VM-Exit, KVM synthesizes a VM-Abort. In short, KVM |
| 4301 |
extends Intel's architectural list of MSRs that cannot be loaded/saved via |
| 4302 |
the VM-Enter/VM-Exit MSR list. It is platform owner's responsibility to |
| 4303 |
to communicate any such restrictions to their end users. |
| 4304 |
|
| 4305 |
x2APIC MSR accesses cannot be filtered (KVM silently ignores filters that |
| 4306 |
cover any x2APIC MSRs). |
| 4307 |
|
| 4308 |
Note, invoking this ioctl while a vCPU is running is inherently racy. However, |
| 4309 |
KVM does guarantee that vCPUs will see either the previous filter or the new |
| 4310 |
filter, e.g. MSRs with identical settings in both the old and new filter will |
| 4311 |
have deterministic behavior. |
| 4312 |
|
| 4313 |
Similarly, if userspace wishes to intercept on denied accesses, |
| 4314 |
KVM_MSR_EXIT_REASON_FILTER must be enabled before activating any filters, and |
| 4315 |
left enabled until after all filters are deactivated. Failure to do so may |
| 4316 |
result in KVM injecting a #GP instead of exiting to userspace. |
| 4317 |
|
| 4318 |
4.98 KVM_CREATE_SPAPR_TCE_64 |
| 4319 |
---------------------------- |
| 4320 |
|
| 4321 |
:Capability: KVM_CAP_SPAPR_TCE_64 |
| 4322 |
:Architectures: powerpc |
| 4323 |
:Type: vm ioctl |
| 4324 |
:Parameters: struct kvm_create_spapr_tce_64 (in) |
| 4325 |
:Returns: file descriptor for manipulating the created TCE table |
| 4326 |
|
| 4327 |
This is an extension for KVM_CAP_SPAPR_TCE which only supports 32bit |
| 4328 |
windows, described in 4.62 KVM_CREATE_SPAPR_TCE |
| 4329 |
|
| 4330 |
This capability uses extended struct in ioctl interface:: |
| 4331 |
|
| 4332 |
/* for KVM_CAP_SPAPR_TCE_64 */ |
| 4333 |
struct kvm_create_spapr_tce_64 { |
| 4334 |
__u64 liobn; |
| 4335 |
__u32 page_shift; |
| 4336 |
__u32 flags; |
| 4337 |
__u64 offset; /* in pages */ |
| 4338 |
__u64 size; /* in pages */ |
| 4339 |
}; |
| 4340 |
|
| 4341 |
The aim of extension is to support an additional bigger DMA window with |
| 4342 |
a variable page size. |
| 4343 |
KVM_CREATE_SPAPR_TCE_64 receives a 64bit window size, an IOMMU page shift and |
| 4344 |
a bus offset of the corresponding DMA window, @size and @offset are numbers |
| 4345 |
of IOMMU pages. |
| 4346 |
|
| 4347 |
@flags are not used at the moment. |
| 4348 |
|
| 4349 |
The rest of functionality is identical to KVM_CREATE_SPAPR_TCE. |
| 4350 |
|
| 4351 |
4.99 KVM_REINJECT_CONTROL |
| 4352 |
------------------------- |
| 4353 |
|
| 4354 |
:Capability: KVM_CAP_REINJECT_CONTROL |
| 4355 |
:Architectures: x86 |
| 4356 |
:Type: vm ioctl |
| 4357 |
:Parameters: struct kvm_reinject_control (in) |
| 4358 |
:Returns: 0 on success, |
| 4359 |
-EFAULT if struct kvm_reinject_control cannot be read, |
| 4360 |
-ENXIO if KVM_CREATE_PIT or KVM_CREATE_PIT2 didn't succeed earlier. |
| 4361 |
|
| 4362 |
i8254 (PIT) has two modes, reinject and !reinject. The default is reinject, |
| 4363 |
where KVM queues elapsed i8254 ticks and monitors completion of interrupt from |
| 4364 |
vector(s) that i8254 injects. Reinject mode dequeues a tick and injects its |
| 4365 |
interrupt whenever there isn't a pending interrupt from i8254. |
| 4366 |
!reinject mode injects an interrupt as soon as a tick arrives. |
| 4367 |
|
| 4368 |
:: |
| 4369 |
|
| 4370 |
struct kvm_reinject_control { |
| 4371 |
__u8 pit_reinject; |
| 4372 |
__u8 reserved[31]; |
| 4373 |
}; |
| 4374 |
|
| 4375 |
pit_reinject = 0 (!reinject mode) is recommended, unless running an old |
| 4376 |
operating system that uses the PIT for timing (e.g. Linux 2.4.x). |
| 4377 |
|
| 4378 |
4.100 KVM_PPC_CONFIGURE_V3_MMU |
| 4379 |
------------------------------ |
| 4380 |
|
| 4381 |
:Capability: KVM_CAP_PPC_MMU_RADIX or KVM_CAP_PPC_MMU_HASH_V3 |
| 4382 |
:Architectures: ppc |
| 4383 |
:Type: vm ioctl |
| 4384 |
:Parameters: struct kvm_ppc_mmuv3_cfg (in) |
| 4385 |
:Returns: 0 on success, |
| 4386 |
-EFAULT if struct kvm_ppc_mmuv3_cfg cannot be read, |
| 4387 |
-EINVAL if the configuration is invalid |
| 4388 |
|
| 4389 |
This ioctl controls whether the guest will use radix or HPT (hashed |
| 4390 |
page table) translation, and sets the pointer to the process table for |
| 4391 |
the guest. |
| 4392 |
|
| 4393 |
:: |
| 4394 |
|
| 4395 |
struct kvm_ppc_mmuv3_cfg { |
| 4396 |
__u64 flags; |
| 4397 |
__u64 process_table; |
| 4398 |
}; |
| 4399 |
|
| 4400 |
There are two bits that can be set in flags; KVM_PPC_MMUV3_RADIX and |
| 4401 |
KVM_PPC_MMUV3_GTSE. KVM_PPC_MMUV3_RADIX, if set, configures the guest |
| 4402 |
to use radix tree translation, and if clear, to use HPT translation. |
| 4403 |
KVM_PPC_MMUV3_GTSE, if set and if KVM permits it, configures the guest |
| 4404 |
to be able to use the global TLB and SLB invalidation instructions; |
| 4405 |
if clear, the guest may not use these instructions. |
| 4406 |
|
| 4407 |
The process_table field specifies the address and size of the guest |
| 4408 |
process table, which is in the guest's space. This field is formatted |
| 4409 |
as the second doubleword of the partition table entry, as defined in |
| 4410 |
the Power ISA V3.00, Book III section 5.7.6.1. |
| 4411 |
|
| 4412 |
4.101 KVM_PPC_GET_RMMU_INFO |
| 4413 |
--------------------------- |
| 4414 |
|
| 4415 |
:Capability: KVM_CAP_PPC_MMU_RADIX |
| 4416 |
:Architectures: ppc |
| 4417 |
:Type: vm ioctl |
| 4418 |
:Parameters: struct kvm_ppc_rmmu_info (out) |
| 4419 |
:Returns: 0 on success, |
| 4420 |
-EFAULT if struct kvm_ppc_rmmu_info cannot be written, |
| 4421 |
-EINVAL if no useful information can be returned |
| 4422 |
|
| 4423 |
This ioctl returns a structure containing two things: (a) a list |
| 4424 |
containing supported radix tree geometries, and (b) a list that maps |
| 4425 |
page sizes to put in the "AP" (actual page size) field for the tlbie |
| 4426 |
(TLB invalidate entry) instruction. |
| 4427 |
|
| 4428 |
:: |
| 4429 |
|
| 4430 |
struct kvm_ppc_rmmu_info { |
| 4431 |
struct kvm_ppc_radix_geom { |
| 4432 |
__u8 page_shift; |
| 4433 |
__u8 level_bits[4]; |
| 4434 |
__u8 pad[3]; |
| 4435 |
} geometries[8]; |
| 4436 |
__u32 ap_encodings[8]; |
| 4437 |
}; |
| 4438 |
|
| 4439 |
The geometries[] field gives up to 8 supported geometries for the |
| 4440 |
radix page table, in terms of the log base 2 of the smallest page |
| 4441 |
size, and the number of bits indexed at each level of the tree, from |
| 4442 |
the PTE level up to the PGD level in that order. Any unused entries |
| 4443 |
will have 0 in the page_shift field. |
| 4444 |
|
| 4445 |
The ap_encodings gives the supported page sizes and their AP field |
| 4446 |
encodings, encoded with the AP value in the top 3 bits and the log |
| 4447 |
base 2 of the page size in the bottom 6 bits. |
| 4448 |
|
| 4449 |
4.102 KVM_PPC_RESIZE_HPT_PREPARE |
| 4450 |
-------------------------------- |
| 4451 |
|
| 4452 |
:Capability: KVM_CAP_SPAPR_RESIZE_HPT |
| 4453 |
:Architectures: powerpc |
| 4454 |
:Type: vm ioctl |
| 4455 |
:Parameters: struct kvm_ppc_resize_hpt (in) |
| 4456 |
:Returns: 0 on successful completion, |
| 4457 |
>0 if a new HPT is being prepared, the value is an estimated |
| 4458 |
number of milliseconds until preparation is complete, |
| 4459 |
-EFAULT if struct kvm_reinject_control cannot be read, |
| 4460 |
-EINVAL if the supplied shift or flags are invalid, |
| 4461 |
-ENOMEM if unable to allocate the new HPT, |
| 4462 |
|
| 4463 |
Used to implement the PAPR extension for runtime resizing of a guest's |
| 4464 |
Hashed Page Table (HPT). Specifically this starts, stops or monitors |
| 4465 |
the preparation of a new potential HPT for the guest, essentially |
| 4466 |
implementing the H_RESIZE_HPT_PREPARE hypercall. |
| 4467 |
|
| 4468 |
:: |
| 4469 |
|
| 4470 |
struct kvm_ppc_resize_hpt { |
| 4471 |
__u64 flags; |
| 4472 |
__u32 shift; |
| 4473 |
__u32 pad; |
| 4474 |
}; |
| 4475 |
|
| 4476 |
If called with shift > 0 when there is no pending HPT for the guest, |
| 4477 |
this begins preparation of a new pending HPT of size 2^(shift) bytes. |
| 4478 |
It then returns a positive integer with the estimated number of |
| 4479 |
milliseconds until preparation is complete. |
| 4480 |
|
| 4481 |
If called when there is a pending HPT whose size does not match that |
| 4482 |
requested in the parameters, discards the existing pending HPT and |
| 4483 |
creates a new one as above. |
| 4484 |
|
| 4485 |
If called when there is a pending HPT of the size requested, will: |
| 4486 |
|
| 4487 |
* If preparation of the pending HPT is already complete, return 0 |
| 4488 |
* If preparation of the pending HPT has failed, return an error |
| 4489 |
code, then discard the pending HPT. |
| 4490 |
* If preparation of the pending HPT is still in progress, return an |
| 4491 |
estimated number of milliseconds until preparation is complete. |
| 4492 |
|
| 4493 |
If called with shift == 0, discards any currently pending HPT and |
| 4494 |
returns 0 (i.e. cancels any in-progress preparation). |
| 4495 |
|
| 4496 |
flags is reserved for future expansion, currently setting any bits in |
| 4497 |
flags will result in an -EINVAL. |
| 4498 |
|
| 4499 |
Normally this will be called repeatedly with the same parameters until |
| 4500 |
it returns <= 0. The first call will initiate preparation, subsequent |
| 4501 |
ones will monitor preparation until it completes or fails. |
| 4502 |
|
| 4503 |
4.103 KVM_PPC_RESIZE_HPT_COMMIT |
| 4504 |
------------------------------- |
| 4505 |
|
| 4506 |
:Capability: KVM_CAP_SPAPR_RESIZE_HPT |
| 4507 |
:Architectures: powerpc |
| 4508 |
:Type: vm ioctl |
| 4509 |
:Parameters: struct kvm_ppc_resize_hpt (in) |
| 4510 |
:Returns: 0 on successful completion, |
| 4511 |
-EFAULT if struct kvm_reinject_control cannot be read, |
| 4512 |
-EINVAL if the supplied shift or flags are invalid, |
| 4513 |
-ENXIO is there is no pending HPT, or the pending HPT doesn't |
| 4514 |
have the requested size, |
| 4515 |
-EBUSY if the pending HPT is not fully prepared, |
| 4516 |
-ENOSPC if there was a hash collision when moving existing |
| 4517 |
HPT entries to the new HPT, |
| 4518 |
-EIO on other error conditions |
| 4519 |
|
| 4520 |
Used to implement the PAPR extension for runtime resizing of a guest's |
| 4521 |
Hashed Page Table (HPT). Specifically this requests that the guest be |
| 4522 |
transferred to working with the new HPT, essentially implementing the |
| 4523 |
H_RESIZE_HPT_COMMIT hypercall. |
| 4524 |
|
| 4525 |
:: |
| 4526 |
|
| 4527 |
struct kvm_ppc_resize_hpt { |
| 4528 |
__u64 flags; |
| 4529 |
__u32 shift; |
| 4530 |
__u32 pad; |
| 4531 |
}; |
| 4532 |
|
| 4533 |
This should only be called after KVM_PPC_RESIZE_HPT_PREPARE has |
| 4534 |
returned 0 with the same parameters. In other cases |
| 4535 |
KVM_PPC_RESIZE_HPT_COMMIT will return an error (usually -ENXIO or |
| 4536 |
-EBUSY, though others may be possible if the preparation was started, |
| 4537 |
but failed). |
| 4538 |
|
| 4539 |
This will have undefined effects on the guest if it has not already |
| 4540 |
placed itself in a quiescent state where no vcpu will make MMU enabled |
| 4541 |
memory accesses. |
| 4542 |
|
| 4543 |
On successful completion, the pending HPT will become the guest's active |
| 4544 |
HPT and the previous HPT will be discarded. |
| 4545 |
|
| 4546 |
On failure, the guest will still be operating on its previous HPT. |
| 4547 |
|
| 4548 |
4.104 KVM_X86_GET_MCE_CAP_SUPPORTED |
| 4549 |
----------------------------------- |
| 4550 |
|
| 4551 |
:Capability: KVM_CAP_MCE |
| 4552 |
:Architectures: x86 |
| 4553 |
:Type: system ioctl |
| 4554 |
:Parameters: u64 mce_cap (out) |
| 4555 |
:Returns: 0 on success, -1 on error |
| 4556 |
|
| 4557 |
Returns supported MCE capabilities. The u64 mce_cap parameter |
| 4558 |
has the same format as the MSR_IA32_MCG_CAP register. Supported |
| 4559 |
capabilities will have the corresponding bits set. |
| 4560 |
|
| 4561 |
4.105 KVM_X86_SETUP_MCE |
| 4562 |
----------------------- |
| 4563 |
|
| 4564 |
:Capability: KVM_CAP_MCE |
| 4565 |
:Architectures: x86 |
| 4566 |
:Type: vcpu ioctl |
| 4567 |
:Parameters: u64 mcg_cap (in) |
| 4568 |
:Returns: 0 on success, |
| 4569 |
-EFAULT if u64 mcg_cap cannot be read, |
| 4570 |
-EINVAL if the requested number of banks is invalid, |
| 4571 |
-EINVAL if requested MCE capability is not supported. |
| 4572 |
|
| 4573 |
Initializes MCE support for use. The u64 mcg_cap parameter |
| 4574 |
has the same format as the MSR_IA32_MCG_CAP register and |
| 4575 |
specifies which capabilities should be enabled. The maximum |
| 4576 |
supported number of error-reporting banks can be retrieved when |
| 4577 |
checking for KVM_CAP_MCE. The supported capabilities can be |
| 4578 |
retrieved with KVM_X86_GET_MCE_CAP_SUPPORTED. |
| 4579 |
|
| 4580 |
4.106 KVM_X86_SET_MCE |
| 4581 |
--------------------- |
| 4582 |
|
| 4583 |
:Capability: KVM_CAP_MCE |
| 4584 |
:Architectures: x86 |
| 4585 |
:Type: vcpu ioctl |
| 4586 |
:Parameters: struct kvm_x86_mce (in) |
| 4587 |
:Returns: 0 on success, |
| 4588 |
-EFAULT if struct kvm_x86_mce cannot be read, |
| 4589 |
-EINVAL if the bank number is invalid, |
| 4590 |
-EINVAL if VAL bit is not set in status field. |
| 4591 |
|
| 4592 |
Inject a machine check error (MCE) into the guest. The input |
| 4593 |
parameter is:: |
| 4594 |
|
| 4595 |
struct kvm_x86_mce { |
| 4596 |
__u64 status; |
| 4597 |
__u64 addr; |
| 4598 |
__u64 misc; |
| 4599 |
__u64 mcg_status; |
| 4600 |
__u8 bank; |
| 4601 |
__u8 pad1[7]; |
| 4602 |
__u64 pad2[3]; |
| 4603 |
}; |
| 4604 |
|
| 4605 |
If the MCE being reported is an uncorrected error, KVM will |
| 4606 |
inject it as an MCE exception into the guest. If the guest |
| 4607 |
MCG_STATUS register reports that an MCE is in progress, KVM |
| 4608 |
causes an KVM_EXIT_SHUTDOWN vmexit. |
| 4609 |
|
| 4610 |
Otherwise, if the MCE is a corrected error, KVM will just |
| 4611 |
store it in the corresponding bank (provided this bank is |
| 4612 |
not holding a previously reported uncorrected error). |
| 4613 |
|
| 4614 |
4.107 KVM_S390_GET_CMMA_BITS |
| 4615 |
---------------------------- |
| 4616 |
|
| 4617 |
:Capability: KVM_CAP_S390_CMMA_MIGRATION |
| 4618 |
:Architectures: s390 |
| 4619 |
:Type: vm ioctl |
| 4620 |
:Parameters: struct kvm_s390_cmma_log (in, out) |
| 4621 |
:Returns: 0 on success, a negative value on error |
| 4622 |
|
| 4623 |
Errors: |
| 4624 |
|
| 4625 |
====== ============================================================= |
| 4626 |
ENOMEM not enough memory can be allocated to complete the task |
| 4627 |
ENXIO if CMMA is not enabled |
| 4628 |
EINVAL if KVM_S390_CMMA_PEEK is not set but migration mode was not enabled |
| 4629 |
EINVAL if KVM_S390_CMMA_PEEK is not set but dirty tracking has been |
| 4630 |
disabled (and thus migration mode was automatically disabled) |
| 4631 |
EFAULT if the userspace address is invalid or if no page table is |
| 4632 |
present for the addresses (e.g. when using hugepages). |
| 4633 |
====== ============================================================= |
| 4634 |
|
| 4635 |
This ioctl is used to get the values of the CMMA bits on the s390 |
| 4636 |
architecture. It is meant to be used in two scenarios: |
| 4637 |
|
| 4638 |
- During live migration to save the CMMA values. Live migration needs |
| 4639 |
to be enabled via the KVM_REQ_START_MIGRATION VM property. |
| 4640 |
- To non-destructively peek at the CMMA values, with the flag |
| 4641 |
KVM_S390_CMMA_PEEK set. |
| 4642 |
|
| 4643 |
The ioctl takes parameters via the kvm_s390_cmma_log struct. The desired |
| 4644 |
values are written to a buffer whose location is indicated via the "values" |
| 4645 |
member in the kvm_s390_cmma_log struct. The values in the input struct are |
| 4646 |
also updated as needed. |
| 4647 |
|
| 4648 |
Each CMMA value takes up one byte. |
| 4649 |
|
| 4650 |
:: |
| 4651 |
|
| 4652 |
struct kvm_s390_cmma_log { |
| 4653 |
__u64 start_gfn; |
| 4654 |
__u32 count; |
| 4655 |
__u32 flags; |
| 4656 |
union { |
| 4657 |
__u64 remaining; |
| 4658 |
__u64 mask; |
| 4659 |
}; |
| 4660 |
__u64 values; |
| 4661 |
}; |
| 4662 |
|
| 4663 |
start_gfn is the number of the first guest frame whose CMMA values are |
| 4664 |
to be retrieved, |
| 4665 |
|
| 4666 |
count is the length of the buffer in bytes, |
| 4667 |
|
| 4668 |
values points to the buffer where the result will be written to. |
| 4669 |
|
| 4670 |
If count is greater than KVM_S390_SKEYS_MAX, then it is considered to be |
| 4671 |
KVM_S390_SKEYS_MAX. KVM_S390_SKEYS_MAX is re-used for consistency with |
| 4672 |
other ioctls. |
| 4673 |
|
| 4674 |
The result is written in the buffer pointed to by the field values, and |
| 4675 |
the values of the input parameter are updated as follows. |
| 4676 |
|
| 4677 |
Depending on the flags, different actions are performed. The only |
| 4678 |
supported flag so far is KVM_S390_CMMA_PEEK. |
| 4679 |
|
| 4680 |
The default behaviour if KVM_S390_CMMA_PEEK is not set is: |
| 4681 |
start_gfn will indicate the first page frame whose CMMA bits were dirty. |
| 4682 |
It is not necessarily the same as the one passed as input, as clean pages |
| 4683 |
are skipped. |
| 4684 |
|
| 4685 |
count will indicate the number of bytes actually written in the buffer. |
| 4686 |
It can (and very often will) be smaller than the input value, since the |
| 4687 |
buffer is only filled until 16 bytes of clean values are found (which |
| 4688 |
are then not copied in the buffer). Since a CMMA migration block needs |
| 4689 |
the base address and the length, for a total of 16 bytes, we will send |
| 4690 |
back some clean data if there is some dirty data afterwards, as long as |
| 4691 |
the size of the clean data does not exceed the size of the header. This |
| 4692 |
allows to minimize the amount of data to be saved or transferred over |
| 4693 |
the network at the expense of more roundtrips to userspace. The next |
| 4694 |
invocation of the ioctl will skip over all the clean values, saving |
| 4695 |
potentially more than just the 16 bytes we found. |
| 4696 |
|
| 4697 |
If KVM_S390_CMMA_PEEK is set: |
| 4698 |
the existing storage attributes are read even when not in migration |
| 4699 |
mode, and no other action is performed; |
| 4700 |
|
| 4701 |
the output start_gfn will be equal to the input start_gfn, |
| 4702 |
|
| 4703 |
the output count will be equal to the input count, except if the end of |
| 4704 |
memory has been reached. |
| 4705 |
|
| 4706 |
In both cases: |
| 4707 |
the field "remaining" will indicate the total number of dirty CMMA values |
| 4708 |
still remaining, or 0 if KVM_S390_CMMA_PEEK is set and migration mode is |
| 4709 |
not enabled. |
| 4710 |
|
| 4711 |
mask is unused. |
| 4712 |
|
| 4713 |
values points to the userspace buffer where the result will be stored. |
| 4714 |
|
| 4715 |
4.108 KVM_S390_SET_CMMA_BITS |
| 4716 |
---------------------------- |
| 4717 |
|
| 4718 |
:Capability: KVM_CAP_S390_CMMA_MIGRATION |
| 4719 |
:Architectures: s390 |
| 4720 |
:Type: vm ioctl |
| 4721 |
:Parameters: struct kvm_s390_cmma_log (in) |
| 4722 |
:Returns: 0 on success, a negative value on error |
| 4723 |
|
| 4724 |
This ioctl is used to set the values of the CMMA bits on the s390 |
| 4725 |
architecture. It is meant to be used during live migration to restore |
| 4726 |
the CMMA values, but there are no restrictions on its use. |
| 4727 |
The ioctl takes parameters via the kvm_s390_cmma_values struct. |
| 4728 |
Each CMMA value takes up one byte. |
| 4729 |
|
| 4730 |
:: |
| 4731 |
|
| 4732 |
struct kvm_s390_cmma_log { |
| 4733 |
__u64 start_gfn; |
| 4734 |
__u32 count; |
| 4735 |
__u32 flags; |
| 4736 |
union { |
| 4737 |
__u64 remaining; |
| 4738 |
__u64 mask; |
| 4739 |
}; |
| 4740 |
__u64 values; |
| 4741 |
}; |
| 4742 |
|
| 4743 |
start_gfn indicates the starting guest frame number, |
| 4744 |
|
| 4745 |
count indicates how many values are to be considered in the buffer, |
| 4746 |
|
| 4747 |
flags is not used and must be 0. |
| 4748 |
|
| 4749 |
mask indicates which PGSTE bits are to be considered. |
| 4750 |
|
| 4751 |
remaining is not used. |
| 4752 |
|
| 4753 |
values points to the buffer in userspace where to store the values. |
| 4754 |
|
| 4755 |
This ioctl can fail with -ENOMEM if not enough memory can be allocated to |
| 4756 |
complete the task, with -ENXIO if CMMA is not enabled, with -EINVAL if |
| 4757 |
the count field is too large (e.g. more than KVM_S390_CMMA_SIZE_MAX) or |
| 4758 |
if the flags field was not 0, with -EFAULT if the userspace address is |
| 4759 |
invalid, if invalid pages are written to (e.g. after the end of memory) |
| 4760 |
or if no page table is present for the addresses (e.g. when using |
| 4761 |
hugepages). |
| 4762 |
|
| 4763 |
4.109 KVM_PPC_GET_CPU_CHAR |
| 4764 |
-------------------------- |
| 4765 |
|
| 4766 |
:Capability: KVM_CAP_PPC_GET_CPU_CHAR |
| 4767 |
:Architectures: powerpc |
| 4768 |
:Type: vm ioctl |
| 4769 |
:Parameters: struct kvm_ppc_cpu_char (out) |
| 4770 |
:Returns: 0 on successful completion, |
| 4771 |
-EFAULT if struct kvm_ppc_cpu_char cannot be written |
| 4772 |
|
| 4773 |
This ioctl gives userspace information about certain characteristics |
| 4774 |
of the CPU relating to speculative execution of instructions and |
| 4775 |
possible information leakage resulting from speculative execution (see |
| 4776 |
CVE-2017-5715, CVE-2017-5753 and CVE-2017-5754). The information is |
| 4777 |
returned in struct kvm_ppc_cpu_char, which looks like this:: |
| 4778 |
|
| 4779 |
struct kvm_ppc_cpu_char { |
| 4780 |
__u64 character; /* characteristics of the CPU */ |
| 4781 |
__u64 behaviour; /* recommended software behaviour */ |
| 4782 |
__u64 character_mask; /* valid bits in character */ |
| 4783 |
__u64 behaviour_mask; /* valid bits in behaviour */ |
| 4784 |
}; |
| 4785 |
|
| 4786 |
For extensibility, the character_mask and behaviour_mask fields |
| 4787 |
indicate which bits of character and behaviour have been filled in by |
| 4788 |
the kernel. If the set of defined bits is extended in future then |
| 4789 |
userspace will be able to tell whether it is running on a kernel that |
| 4790 |
knows about the new bits. |
| 4791 |
|
| 4792 |
The character field describes attributes of the CPU which can help |
| 4793 |
with preventing inadvertent information disclosure - specifically, |
| 4794 |
whether there is an instruction to flash-invalidate the L1 data cache |
| 4795 |
(ori 30,30,0 or mtspr SPRN_TRIG2,rN), whether the L1 data cache is set |
| 4796 |
to a mode where entries can only be used by the thread that created |
| 4797 |
them, whether the bcctr[l] instruction prevents speculation, and |
| 4798 |
whether a speculation barrier instruction (ori 31,31,0) is provided. |
| 4799 |
|
| 4800 |
The behaviour field describes actions that software should take to |
| 4801 |
prevent inadvertent information disclosure, and thus describes which |
| 4802 |
vulnerabilities the hardware is subject to; specifically whether the |
| 4803 |
L1 data cache should be flushed when returning to user mode from the |
| 4804 |
kernel, and whether a speculation barrier should be placed between an |
| 4805 |
array bounds check and the array access. |
| 4806 |
|
| 4807 |
These fields use the same bit definitions as the new |
| 4808 |
H_GET_CPU_CHARACTERISTICS hypercall. |
| 4809 |
|
| 4810 |
4.110 KVM_MEMORY_ENCRYPT_OP |
| 4811 |
--------------------------- |
| 4812 |
|
| 4813 |
:Capability: basic |
| 4814 |
:Architectures: x86 |
| 4815 |
:Type: vm ioctl, vcpu ioctl |
| 4816 |
:Parameters: an opaque platform specific structure (in/out) |
| 4817 |
:Returns: 0 on success; -1 on error |
| 4818 |
|
| 4819 |
If the platform supports creating encrypted VMs then this ioctl can be used |
| 4820 |
for issuing platform-specific memory encryption commands to manage those |
| 4821 |
encrypted VMs. |
| 4822 |
|
| 4823 |
Currently, this ioctl is used for issuing both Secure Encrypted Virtualization |
| 4824 |
(SEV) commands on AMD Processors and Trusted Domain Extensions (TDX) commands |
| 4825 |
on Intel Processors. The detailed commands are defined in |
| 4826 |
Documentation/virt/kvm/x86/amd-memory-encryption.rst and |
| 4827 |
Documentation/virt/kvm/x86/intel-tdx.rst. |
| 4828 |
|
| 4829 |
4.111 KVM_MEMORY_ENCRYPT_REG_REGION |
| 4830 |
----------------------------------- |
| 4831 |
|
| 4832 |
:Capability: basic |
| 4833 |
:Architectures: x86 |
| 4834 |
:Type: system |
| 4835 |
:Parameters: struct kvm_enc_region (in) |
| 4836 |
:Returns: 0 on success; -1 on error |
| 4837 |
|
| 4838 |
This ioctl can be used to register a guest memory region which may |
| 4839 |
contain encrypted data (e.g. guest RAM, SMRAM etc). |
| 4840 |
|
| 4841 |
It is used in the SEV-enabled guest. When encryption is enabled, a guest |
| 4842 |
memory region may contain encrypted data. The SEV memory encryption |
| 4843 |
engine uses a tweak such that two identical plaintext pages, each at |
| 4844 |
different locations will have differing ciphertexts. So swapping or |
| 4845 |
moving ciphertext of those pages will not result in plaintext being |
| 4846 |
swapped. So relocating (or migrating) physical backing pages for the SEV |
| 4847 |
guest will require some additional steps. |
| 4848 |
|
| 4849 |
Note: The current SEV key management spec does not provide commands to |
| 4850 |
swap or migrate (move) ciphertext pages. Hence, for now we pin the guest |
| 4851 |
memory region registered with the ioctl. |
| 4852 |
|
| 4853 |
4.112 KVM_MEMORY_ENCRYPT_UNREG_REGION |
| 4854 |
------------------------------------- |
| 4855 |
|
| 4856 |
:Capability: basic |
| 4857 |
:Architectures: x86 |
| 4858 |
:Type: system |
| 4859 |
:Parameters: struct kvm_enc_region (in) |
| 4860 |
:Returns: 0 on success; -1 on error |
| 4861 |
|
| 4862 |
This ioctl can be used to unregister the guest memory region registered |
| 4863 |
with KVM_MEMORY_ENCRYPT_REG_REGION ioctl above. |
| 4864 |
|
| 4865 |
4.113 KVM_HYPERV_EVENTFD |
| 4866 |
------------------------ |
| 4867 |
|
| 4868 |
:Capability: KVM_CAP_HYPERV_EVENTFD |
| 4869 |
:Architectures: x86 |
| 4870 |
:Type: vm ioctl |
| 4871 |
:Parameters: struct kvm_hyperv_eventfd (in) |
| 4872 |
|
| 4873 |
This ioctl (un)registers an eventfd to receive notifications from the guest on |
| 4874 |
the specified Hyper-V connection id through the SIGNAL_EVENT hypercall, without |
| 4875 |
causing a user exit. SIGNAL_EVENT hypercall with non-zero event flag number |
| 4876 |
(bits 24-31) still triggers a KVM_EXIT_HYPERV_HCALL user exit. |
| 4877 |
|
| 4878 |
:: |
| 4879 |
|
| 4880 |
struct kvm_hyperv_eventfd { |
| 4881 |
__u32 conn_id; |
| 4882 |
__s32 fd; |
| 4883 |
__u32 flags; |
| 4884 |
__u32 padding[3]; |
| 4885 |
}; |
| 4886 |
|
| 4887 |
The conn_id field should fit within 24 bits:: |
| 4888 |
|
| 4889 |
#define KVM_HYPERV_CONN_ID_MASK 0x00ffffff |
| 4890 |
|
| 4891 |
The acceptable values for the flags field are:: |
| 4892 |
|
| 4893 |
#define KVM_HYPERV_EVENTFD_DEASSIGN (1 << 0) |
| 4894 |
|
| 4895 |
:Returns: 0 on success, |
| 4896 |
-EINVAL if conn_id or flags is outside the allowed range, |
| 4897 |
-ENOENT on deassign if the conn_id isn't registered, |
| 4898 |
-EEXIST on assign if the conn_id is already registered |
| 4899 |
|
| 4900 |
4.114 KVM_GET_NESTED_STATE |
| 4901 |
-------------------------- |
| 4902 |
|
| 4903 |
:Capability: KVM_CAP_NESTED_STATE |
| 4904 |
:Architectures: x86 |
| 4905 |
:Type: vcpu ioctl |
| 4906 |
:Parameters: struct kvm_nested_state (in/out) |
| 4907 |
:Returns: 0 on success, -1 on error |
| 4908 |
|
| 4909 |
Errors: |
| 4910 |
|
| 4911 |
===== ============================================================= |
| 4912 |
E2BIG the total state size exceeds the value of 'size' specified by |
| 4913 |
the user; the size required will be written into size. |
| 4914 |
===== ============================================================= |
| 4915 |
|
| 4916 |
:: |
| 4917 |
|
| 4918 |
struct kvm_nested_state { |
| 4919 |
__u16 flags; |
| 4920 |
__u16 format; |
| 4921 |
__u32 size; |
| 4922 |
|
| 4923 |
union { |
| 4924 |
struct kvm_vmx_nested_state_hdr vmx; |
| 4925 |
struct kvm_svm_nested_state_hdr svm; |
| 4926 |
|
| 4927 |
/* Pad the header to 128 bytes. */ |
| 4928 |
__u8 pad[120]; |
| 4929 |
} hdr; |
| 4930 |
|
| 4931 |
union { |
| 4932 |
struct kvm_vmx_nested_state_data vmx[0]; |
| 4933 |
struct kvm_svm_nested_state_data svm[0]; |
| 4934 |
} data; |
| 4935 |
}; |
| 4936 |
|
| 4937 |
#define KVM_STATE_NESTED_GUEST_MODE 0x00000001 |
| 4938 |
#define KVM_STATE_NESTED_RUN_PENDING 0x00000002 |
| 4939 |
#define KVM_STATE_NESTED_EVMCS 0x00000004 |
| 4940 |
|
| 4941 |
#define KVM_STATE_NESTED_FORMAT_VMX 0 |
| 4942 |
#define KVM_STATE_NESTED_FORMAT_SVM 1 |
| 4943 |
|
| 4944 |
#define KVM_STATE_NESTED_VMX_VMCS_SIZE 0x1000 |
| 4945 |
|
| 4946 |
#define KVM_STATE_NESTED_VMX_SMM_GUEST_MODE 0x00000001 |
| 4947 |
#define KVM_STATE_NESTED_VMX_SMM_VMXON 0x00000002 |
| 4948 |
|
| 4949 |
#define KVM_STATE_VMX_PREEMPTION_TIMER_DEADLINE 0x00000001 |
| 4950 |
|
| 4951 |
struct kvm_vmx_nested_state_hdr { |
| 4952 |
__u64 vmxon_pa; |
| 4953 |
__u64 vmcs12_pa; |
| 4954 |
|
| 4955 |
struct { |
| 4956 |
__u16 flags; |
| 4957 |
} smm; |
| 4958 |
|
| 4959 |
__u32 flags; |
| 4960 |
__u64 preemption_timer_deadline; |
| 4961 |
}; |
| 4962 |
|
| 4963 |
struct kvm_vmx_nested_state_data { |
| 4964 |
__u8 vmcs12[KVM_STATE_NESTED_VMX_VMCS_SIZE]; |
| 4965 |
__u8 shadow_vmcs12[KVM_STATE_NESTED_VMX_VMCS_SIZE]; |
| 4966 |
}; |
| 4967 |
|
| 4968 |
This ioctl copies the vcpu's nested virtualization state from the kernel to |
| 4969 |
userspace. |
| 4970 |
|
| 4971 |
The maximum size of the state can be retrieved by passing KVM_CAP_NESTED_STATE |
| 4972 |
to the KVM_CHECK_EXTENSION ioctl(). |
| 4973 |
|
| 4974 |
4.115 KVM_SET_NESTED_STATE |
| 4975 |
-------------------------- |
| 4976 |
|
| 4977 |
:Capability: KVM_CAP_NESTED_STATE |
| 4978 |
:Architectures: x86 |
| 4979 |
:Type: vcpu ioctl |
| 4980 |
:Parameters: struct kvm_nested_state (in) |
| 4981 |
:Returns: 0 on success, -1 on error |
| 4982 |
|
| 4983 |
This copies the vcpu's kvm_nested_state struct from userspace to the kernel. |
| 4984 |
For the definition of struct kvm_nested_state, see KVM_GET_NESTED_STATE. |
| 4985 |
|
| 4986 |
4.116 KVM_(UN)REGISTER_COALESCED_MMIO |
| 4987 |
------------------------------------- |
| 4988 |
|
| 4989 |
:Capability: KVM_CAP_COALESCED_MMIO (for coalesced mmio) |
| 4990 |
KVM_CAP_COALESCED_PIO (for coalesced pio) |
| 4991 |
:Architectures: all |
| 4992 |
:Type: vm ioctl |
| 4993 |
:Parameters: struct kvm_coalesced_mmio_zone |
| 4994 |
:Returns: 0 on success, < 0 on error |
| 4995 |
|
| 4996 |
Coalesced I/O is a performance optimization that defers hardware |
| 4997 |
register write emulation so that userspace exits are avoided. It is |
| 4998 |
typically used to reduce the overhead of emulating frequently accessed |
| 4999 |
hardware registers. |
| 5000 |
|
| 5001 |
When a hardware register is configured for coalesced I/O, write accesses |
| 5002 |
do not exit to userspace and their value is recorded in a ring buffer |
| 5003 |
that is shared between kernel and userspace. |
| 5004 |
|
| 5005 |
Coalesced I/O is used if one or more write accesses to a hardware |
| 5006 |
register can be deferred until a read or a write to another hardware |
| 5007 |
register on the same device. This last access will cause a vmexit and |
| 5008 |
userspace will process accesses from the ring buffer before emulating |
| 5009 |
it. That will avoid exiting to userspace on repeated writes. |
| 5010 |
|
| 5011 |
Coalesced pio is based on coalesced mmio. There is little difference |
| 5012 |
between coalesced mmio and pio except that coalesced pio records accesses |
| 5013 |
to I/O ports. |
| 5014 |
|
| 5015 |
4.117 KVM_CLEAR_DIRTY_LOG |
| 5016 |
------------------------- |
| 5017 |
|
| 5018 |
:Capability: KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 |
| 5019 |
:Architectures: x86, arm64, mips |
| 5020 |
:Type: vm ioctl |
| 5021 |
:Parameters: struct kvm_clear_dirty_log (in) |
| 5022 |
:Returns: 0 on success, -1 on error |
| 5023 |
|
| 5024 |
:: |
| 5025 |
|
| 5026 |
/* for KVM_CLEAR_DIRTY_LOG */ |
| 5027 |
struct kvm_clear_dirty_log { |
| 5028 |
__u32 slot; |
| 5029 |
__u32 num_pages; |
| 5030 |
__u64 first_page; |
| 5031 |
union { |
| 5032 |
void __user *dirty_bitmap; /* one bit per page */ |
| 5033 |
__u64 padding; |
| 5034 |
}; |
| 5035 |
}; |
| 5036 |
|
| 5037 |
The ioctl clears the dirty status of pages in a memory slot, according to |
| 5038 |
the bitmap that is passed in struct kvm_clear_dirty_log's dirty_bitmap |
| 5039 |
field. Bit 0 of the bitmap corresponds to page "first_page" in the |
| 5040 |
memory slot, and num_pages is the size in bits of the input bitmap. |
| 5041 |
first_page must be a multiple of 64; num_pages must also be a multiple of |
| 5042 |
64 unless first_page + num_pages is the size of the memory slot. For each |
| 5043 |
bit that is set in the input bitmap, the corresponding page is marked "clean" |
| 5044 |
in KVM's dirty bitmap, and dirty tracking is re-enabled for that page |
| 5045 |
(for example via write-protection, or by clearing the dirty bit in |
| 5046 |
a page table entry). |
| 5047 |
|
| 5048 |
If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 of slot field specifies |
| 5049 |
the address space for which you want to clear the dirty status. See |
| 5050 |
KVM_SET_USER_MEMORY_REGION for details on the usage of slot field. |
| 5051 |
|
| 5052 |
This ioctl is mostly useful when KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 |
| 5053 |
is enabled; for more information, see the description of the capability. |
| 5054 |
However, it can always be used as long as KVM_CHECK_EXTENSION confirms |
| 5055 |
that KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 is present. |
| 5056 |
|
| 5057 |
4.118 KVM_GET_SUPPORTED_HV_CPUID |
| 5058 |
-------------------------------- |
| 5059 |
|
| 5060 |
:Capability: KVM_CAP_HYPERV_CPUID (vcpu), KVM_CAP_SYS_HYPERV_CPUID (system) |
| 5061 |
:Architectures: x86 |
| 5062 |
:Type: system ioctl, vcpu ioctl |
| 5063 |
:Parameters: struct kvm_cpuid2 (in/out) |
| 5064 |
:Returns: 0 on success, -1 on error |
| 5065 |
|
| 5066 |
:: |
| 5067 |
|
| 5068 |
struct kvm_cpuid2 { |
| 5069 |
__u32 nent; |
| 5070 |
__u32 padding; |
| 5071 |
struct kvm_cpuid_entry2 entries[0]; |
| 5072 |
}; |
| 5073 |
|
| 5074 |
struct kvm_cpuid_entry2 { |
| 5075 |
__u32 function; |
| 5076 |
__u32 index; |
| 5077 |
__u32 flags; |
| 5078 |
__u32 eax; |
| 5079 |
__u32 ebx; |
| 5080 |
__u32 ecx; |
| 5081 |
__u32 edx; |
| 5082 |
__u32 padding[3]; |
| 5083 |
}; |
| 5084 |
|
| 5085 |
This ioctl returns x86 cpuid features leaves related to Hyper-V emulation in |
| 5086 |
KVM. Userspace can use the information returned by this ioctl to construct |
| 5087 |
cpuid information presented to guests consuming Hyper-V enlightenments (e.g. |
| 5088 |
Windows or Hyper-V guests). |
| 5089 |
|
| 5090 |
CPUID feature leaves returned by this ioctl are defined by Hyper-V Top Level |
| 5091 |
Functional Specification (TLFS). These leaves can't be obtained with |
| 5092 |
KVM_GET_SUPPORTED_CPUID ioctl because some of them intersect with KVM feature |
| 5093 |
leaves (0x40000000, 0x40000001). |
| 5094 |
|
| 5095 |
Currently, the following list of CPUID leaves are returned: |
| 5096 |
|
| 5097 |
- HYPERV_CPUID_VENDOR_AND_MAX_FUNCTIONS |
| 5098 |
- HYPERV_CPUID_INTERFACE |
| 5099 |
- HYPERV_CPUID_VERSION |
| 5100 |
- HYPERV_CPUID_FEATURES |
| 5101 |
- HYPERV_CPUID_ENLIGHTMENT_INFO |
| 5102 |
- HYPERV_CPUID_IMPLEMENT_LIMITS |
| 5103 |
- HYPERV_CPUID_NESTED_FEATURES |
| 5104 |
- HYPERV_CPUID_SYNDBG_VENDOR_AND_MAX_FUNCTIONS |
| 5105 |
- HYPERV_CPUID_SYNDBG_INTERFACE |
| 5106 |
- HYPERV_CPUID_SYNDBG_PLATFORM_CAPABILITIES |
| 5107 |
|
| 5108 |
Userspace invokes KVM_GET_SUPPORTED_HV_CPUID by passing a kvm_cpuid2 structure |
| 5109 |
with the 'nent' field indicating the number of entries in the variable-size |
| 5110 |
array 'entries'. If the number of entries is too low to describe all Hyper-V |
| 5111 |
feature leaves, an error (E2BIG) is returned. If the number is more or equal |
| 5112 |
to the number of Hyper-V feature leaves, the 'nent' field is adjusted to the |
| 5113 |
number of valid entries in the 'entries' array, which is then filled. |
| 5114 |
|
| 5115 |
'index' and 'flags' fields in 'struct kvm_cpuid_entry2' are currently reserved, |
| 5116 |
userspace should not expect to get any particular value there. |
| 5117 |
|
| 5118 |
Note, vcpu version of KVM_GET_SUPPORTED_HV_CPUID is currently deprecated. Unlike |
| 5119 |
system ioctl which exposes all supported feature bits unconditionally, vcpu |
| 5120 |
version has the following quirks: |
| 5121 |
|
| 5122 |
- HYPERV_CPUID_NESTED_FEATURES leaf and HV_X64_ENLIGHTENED_VMCS_RECOMMENDED |
| 5123 |
feature bit are only exposed when Enlightened VMCS was previously enabled |
| 5124 |
on the corresponding vCPU (KVM_CAP_HYPERV_ENLIGHTENED_VMCS). |
| 5125 |
- HV_STIMER_DIRECT_MODE_AVAILABLE bit is only exposed with in-kernel LAPIC. |
| 5126 |
(presumes KVM_CREATE_IRQCHIP has already been called). |
| 5127 |
|
| 5128 |
4.119 KVM_ARM_VCPU_FINALIZE |
| 5129 |
--------------------------- |
| 5130 |
|
| 5131 |
:Architectures: arm64 |
| 5132 |
:Type: vcpu ioctl |
| 5133 |
:Parameters: int feature (in) |
| 5134 |
:Returns: 0 on success, -1 on error |
| 5135 |
|
| 5136 |
Errors: |
| 5137 |
|
| 5138 |
====== ============================================================== |
| 5139 |
EPERM feature not enabled, needs configuration, or already finalized |
| 5140 |
EINVAL feature unknown or not present |
| 5141 |
====== ============================================================== |
| 5142 |
|
| 5143 |
Recognised values for feature: |
| 5144 |
|
| 5145 |
===== =========================================== |
| 5146 |
arm64 KVM_ARM_VCPU_SVE (requires KVM_CAP_ARM_SVE) |
| 5147 |
===== =========================================== |
| 5148 |
|
| 5149 |
Finalizes the configuration of the specified vcpu feature. |
| 5150 |
|
| 5151 |
The vcpu must already have been initialised, enabling the affected feature, by |
| 5152 |
means of a successful :ref:`KVM_ARM_VCPU_INIT <KVM_ARM_VCPU_INIT>` call with the |
| 5153 |
appropriate flag set in features[]. |
| 5154 |
|
| 5155 |
For affected vcpu features, this is a mandatory step that must be performed |
| 5156 |
before the vcpu is fully usable. |
| 5157 |
|
| 5158 |
Between KVM_ARM_VCPU_INIT and KVM_ARM_VCPU_FINALIZE, the feature may be |
| 5159 |
configured by use of ioctls such as KVM_SET_ONE_REG. The exact configuration |
| 5160 |
that should be performed and how to do it are feature-dependent. |
| 5161 |
|
| 5162 |
Other calls that depend on a particular feature being finalized, such as |
| 5163 |
KVM_RUN, KVM_GET_REG_LIST, KVM_GET_ONE_REG and KVM_SET_ONE_REG, will fail with |
| 5164 |
-EPERM unless the feature has already been finalized by means of a |
| 5165 |
KVM_ARM_VCPU_FINALIZE call. |
| 5166 |
|
| 5167 |
See KVM_ARM_VCPU_INIT for details of vcpu features that require finalization |
| 5168 |
using this ioctl. |
| 5169 |
|
| 5170 |
4.120 KVM_SET_PMU_EVENT_FILTER |
| 5171 |
------------------------------ |
| 5172 |
|
| 5173 |
:Capability: KVM_CAP_PMU_EVENT_FILTER |
| 5174 |
:Architectures: x86 |
| 5175 |
:Type: vm ioctl |
| 5176 |
:Parameters: struct kvm_pmu_event_filter (in) |
| 5177 |
:Returns: 0 on success, -1 on error |
| 5178 |
|
| 5179 |
Errors: |
| 5180 |
|
| 5181 |
====== ============================================================ |
| 5182 |
EFAULT args[0] cannot be accessed |
| 5183 |
EINVAL args[0] contains invalid data in the filter or filter events |
| 5184 |
E2BIG nevents is too large |
| 5185 |
EBUSY not enough memory to allocate the filter |
| 5186 |
====== ============================================================ |
| 5187 |
|
| 5188 |
:: |
| 5189 |
|
| 5190 |
struct kvm_pmu_event_filter { |
| 5191 |
__u32 action; |
| 5192 |
__u32 nevents; |
| 5193 |
__u32 fixed_counter_bitmap; |
| 5194 |
__u32 flags; |
| 5195 |
__u32 pad[4]; |
| 5196 |
__u64 events[0]; |
| 5197 |
}; |
| 5198 |
|
| 5199 |
This ioctl restricts the set of PMU events the guest can program by limiting |
| 5200 |
which event select and unit mask combinations are permitted. |
| 5201 |
|
| 5202 |
The argument holds a list of filter events which will be allowed or denied. |
| 5203 |
|
| 5204 |
Filter events only control general purpose counters; fixed purpose counters |
| 5205 |
are controlled by the fixed_counter_bitmap. |
| 5206 |
|
| 5207 |
Valid values for 'flags':: |
| 5208 |
|
| 5209 |
``0`` |
| 5210 |
|
| 5211 |
To use this mode, clear the 'flags' field. |
| 5212 |
|
| 5213 |
In this mode each event will contain an event select + unit mask. |
| 5214 |
|
| 5215 |
When the guest attempts to program the PMU the guest's event select + |
| 5216 |
unit mask is compared against the filter events to determine whether the |
| 5217 |
guest should have access. |
| 5218 |
|
| 5219 |
``KVM_PMU_EVENT_FLAG_MASKED_EVENTS`` |
| 5220 |
:Capability: KVM_CAP_PMU_EVENT_MASKED_EVENTS |
| 5221 |
|
| 5222 |
In this mode each filter event will contain an event select, mask, match, and |
| 5223 |
exclude value. To encode a masked event use:: |
| 5224 |
|
| 5225 |
KVM_PMU_ENCODE_MASKED_ENTRY() |
| 5226 |
|
| 5227 |
An encoded event will follow this layout:: |
| 5228 |
|
| 5229 |
Bits Description |
| 5230 |
---- ----------- |
| 5231 |
7:0 event select (low bits) |
| 5232 |
15:8 umask match |
| 5233 |
31:16 unused |
| 5234 |
35:32 event select (high bits) |
| 5235 |
36:54 unused |
| 5236 |
55 exclude bit |
| 5237 |
63:56 umask mask |
| 5238 |
|
| 5239 |
When the guest attempts to program the PMU, these steps are followed in |
| 5240 |
determining if the guest should have access: |
| 5241 |
|
| 5242 |
1. Match the event select from the guest against the filter events. |
| 5243 |
2. If a match is found, match the guest's unit mask to the mask and match |
| 5244 |
values of the included filter events. |
| 5245 |
I.e. (unit mask & mask) == match && !exclude. |
| 5246 |
3. If a match is found, match the guest's unit mask to the mask and match |
| 5247 |
values of the excluded filter events. |
| 5248 |
I.e. (unit mask & mask) == match && exclude. |
| 5249 |
4. |
| 5250 |
a. If an included match is found and an excluded match is not found, filter |
| 5251 |
the event. |
| 5252 |
b. For everything else, do not filter the event. |
| 5253 |
5. |
| 5254 |
a. If the event is filtered and it's an allow list, allow the guest to |
| 5255 |
program the event. |
| 5256 |
b. If the event is filtered and it's a deny list, do not allow the guest to |
| 5257 |
program the event. |
| 5258 |
|
| 5259 |
When setting a new pmu event filter, -EINVAL will be returned if any of the |
| 5260 |
unused fields are set or if any of the high bits (35:32) in the event |
| 5261 |
select are set when called on Intel. |
| 5262 |
|
| 5263 |
Valid values for 'action':: |
| 5264 |
|
| 5265 |
#define KVM_PMU_EVENT_ALLOW 0 |
| 5266 |
#define KVM_PMU_EVENT_DENY 1 |
| 5267 |
|
| 5268 |
Via this API, KVM userspace can also control the behavior of the VM's fixed |
| 5269 |
counters (if any) by configuring the "action" and "fixed_counter_bitmap" fields. |
| 5270 |
|
| 5271 |
Specifically, KVM follows the following pseudo-code when determining whether to |
| 5272 |
allow the guest FixCtr[i] to count its pre-defined fixed event:: |
| 5273 |
|
| 5274 |
FixCtr[i]_is_allowed = (action == ALLOW) && (bitmap & BIT(i)) || |
| 5275 |
(action == DENY) && !(bitmap & BIT(i)); |
| 5276 |
FixCtr[i]_is_denied = !FixCtr[i]_is_allowed; |
| 5277 |
|
| 5278 |
KVM always consumes fixed_counter_bitmap, it's userspace's responsibility to |
| 5279 |
ensure fixed_counter_bitmap is set correctly, e.g. if userspace wants to define |
| 5280 |
a filter that only affects general purpose counters. |
| 5281 |
|
| 5282 |
Note, the "events" field also applies to fixed counters' hardcoded event_select |
| 5283 |
and unit_mask values. "fixed_counter_bitmap" has higher priority than "events" |
| 5284 |
if there is a contradiction between the two. |
| 5285 |
|
| 5286 |
4.121 KVM_PPC_SVM_OFF |
| 5287 |
--------------------- |
| 5288 |
|
| 5289 |
:Capability: basic |
| 5290 |
:Architectures: powerpc |
| 5291 |
:Type: vm ioctl |
| 5292 |
:Parameters: none |
| 5293 |
:Returns: 0 on successful completion, |
| 5294 |
|
| 5295 |
Errors: |
| 5296 |
|
| 5297 |
====== ================================================================ |
| 5298 |
EINVAL if ultravisor failed to terminate the secure guest |
| 5299 |
ENOMEM if hypervisor failed to allocate new radix page tables for guest |
| 5300 |
====== ================================================================ |
| 5301 |
|
| 5302 |
This ioctl is used to turn off the secure mode of the guest or transition |
| 5303 |
the guest from secure mode to normal mode. This is invoked when the guest |
| 5304 |
is reset. This has no effect if called for a normal guest. |
| 5305 |
|
| 5306 |
This ioctl issues an ultravisor call to terminate the secure guest, |
| 5307 |
unpins the VPA pages and releases all the device pages that are used to |
| 5308 |
track the secure pages by hypervisor. |
| 5309 |
|
| 5310 |
4.122 KVM_S390_NORMAL_RESET |
| 5311 |
--------------------------- |
| 5312 |
|
| 5313 |
:Capability: KVM_CAP_S390_VCPU_RESETS |
| 5314 |
:Architectures: s390 |
| 5315 |
:Type: vcpu ioctl |
| 5316 |
:Parameters: none |
| 5317 |
:Returns: 0 |
| 5318 |
|
| 5319 |
This ioctl resets VCPU registers and control structures according to |
| 5320 |
the cpu reset definition in the POP (Principles Of Operation). |
| 5321 |
|
| 5322 |
4.123 KVM_S390_INITIAL_RESET |
| 5323 |
---------------------------- |
| 5324 |
|
| 5325 |
:Capability: basic |
| 5326 |
:Architectures: s390 |
| 5327 |
:Type: vcpu ioctl |
| 5328 |
:Parameters: none |
| 5329 |
:Returns: 0 |
| 5330 |
|
| 5331 |
This ioctl resets VCPU registers and control structures according to |
| 5332 |
the initial cpu reset definition in the POP. However, the cpu is not |
| 5333 |
put into ESA mode. This reset is a superset of the normal reset. |
| 5334 |
|
| 5335 |
4.124 KVM_S390_CLEAR_RESET |
| 5336 |
-------------------------- |
| 5337 |
|
| 5338 |
:Capability: KVM_CAP_S390_VCPU_RESETS |
| 5339 |
:Architectures: s390 |
| 5340 |
:Type: vcpu ioctl |
| 5341 |
:Parameters: none |
| 5342 |
:Returns: 0 |
| 5343 |
|
| 5344 |
This ioctl resets VCPU registers and control structures according to |
| 5345 |
the clear cpu reset definition in the POP. However, the cpu is not put |
| 5346 |
into ESA mode. This reset is a superset of the initial reset. |
| 5347 |
|
| 5348 |
|
| 5349 |
4.125 KVM_S390_PV_COMMAND |
| 5350 |
------------------------- |
| 5351 |
|
| 5352 |
:Capability: KVM_CAP_S390_PROTECTED |
| 5353 |
:Architectures: s390 |
| 5354 |
:Type: vm ioctl |
| 5355 |
:Parameters: struct kvm_pv_cmd |
| 5356 |
:Returns: 0 on success, < 0 on error |
| 5357 |
|
| 5358 |
:: |
| 5359 |
|
| 5360 |
struct kvm_pv_cmd { |
| 5361 |
__u32 cmd; /* Command to be executed */ |
| 5362 |
__u16 rc; /* Ultravisor return code */ |
| 5363 |
__u16 rrc; /* Ultravisor return reason code */ |
| 5364 |
__u64 data; /* Data or address */ |
| 5365 |
__u32 flags; /* flags for future extensions. Must be 0 for now */ |
| 5366 |
__u32 reserved[3]; |
| 5367 |
}; |
| 5368 |
|
| 5369 |
**Ultravisor return codes** |
| 5370 |
The Ultravisor return (reason) codes are provided by the kernel if a |
| 5371 |
Ultravisor call has been executed to achieve the results expected by |
| 5372 |
the command. Therefore they are independent of the IOCTL return |
| 5373 |
code. If KVM changes `rc`, its value will always be greater than 0 |
| 5374 |
hence setting it to 0 before issuing a PV command is advised to be |
| 5375 |
able to detect a change of `rc`. |
| 5376 |
|
| 5377 |
**cmd values:** |
| 5378 |
|
| 5379 |
KVM_PV_ENABLE |
| 5380 |
Allocate memory and register the VM with the Ultravisor, thereby |
| 5381 |
donating memory to the Ultravisor that will become inaccessible to |
| 5382 |
KVM. All existing CPUs are converted to protected ones. After this |
| 5383 |
command has succeeded, any CPU added via hotplug will become |
| 5384 |
protected during its creation as well. |
| 5385 |
|
| 5386 |
Errors: |
| 5387 |
|
| 5388 |
===== ============================= |
| 5389 |
EINTR an unmasked signal is pending |
| 5390 |
===== ============================= |
| 5391 |
|
| 5392 |
KVM_PV_DISABLE |
| 5393 |
Deregister the VM from the Ultravisor and reclaim the memory that had |
| 5394 |
been donated to the Ultravisor, making it usable by the kernel again. |
| 5395 |
All registered VCPUs are converted back to non-protected ones. If a |
| 5396 |
previous protected VM had been prepared for asynchronous teardown with |
| 5397 |
KVM_PV_ASYNC_CLEANUP_PREPARE and not subsequently torn down with |
| 5398 |
KVM_PV_ASYNC_CLEANUP_PERFORM, it will be torn down in this call |
| 5399 |
together with the current protected VM. |
| 5400 |
|
| 5401 |
KVM_PV_VM_SET_SEC_PARMS |
| 5402 |
Pass the image header from VM memory to the Ultravisor in |
| 5403 |
preparation of image unpacking and verification. |
| 5404 |
|
| 5405 |
KVM_PV_VM_UNPACK |
| 5406 |
Unpack (protect and decrypt) a page of the encrypted boot image. |
| 5407 |
|
| 5408 |
KVM_PV_VM_VERIFY |
| 5409 |
Verify the integrity of the unpacked image. Only if this succeeds, |
| 5410 |
KVM is allowed to start protected VCPUs. |
| 5411 |
|
| 5412 |
KVM_PV_INFO |
| 5413 |
:Capability: KVM_CAP_S390_PROTECTED_DUMP |
| 5414 |
|
| 5415 |
Presents an API that provides Ultravisor related data to userspace |
| 5416 |
via subcommands. len_max is the size of the user space buffer, |
| 5417 |
len_written is KVM's indication of how much bytes of that buffer |
| 5418 |
were actually written to. len_written can be used to determine the |
| 5419 |
valid fields if more response fields are added in the future. |
| 5420 |
|
| 5421 |
:: |
| 5422 |
|
| 5423 |
enum pv_cmd_info_id { |
| 5424 |
KVM_PV_INFO_VM, |
| 5425 |
KVM_PV_INFO_DUMP, |
| 5426 |
}; |
| 5427 |
|
| 5428 |
struct kvm_s390_pv_info_header { |
| 5429 |
__u32 id; |
| 5430 |
__u32 len_max; |
| 5431 |
__u32 len_written; |
| 5432 |
__u32 reserved; |
| 5433 |
}; |
| 5434 |
|
| 5435 |
struct kvm_s390_pv_info { |
| 5436 |
struct kvm_s390_pv_info_header header; |
| 5437 |
struct kvm_s390_pv_info_dump dump; |
| 5438 |
struct kvm_s390_pv_info_vm vm; |
| 5439 |
}; |
| 5440 |
|
| 5441 |
**subcommands:** |
| 5442 |
|
| 5443 |
KVM_PV_INFO_VM |
| 5444 |
This subcommand provides basic Ultravisor information for PV |
| 5445 |
hosts. These values are likely also exported as files in the sysfs |
| 5446 |
firmware UV query interface but they are more easily available to |
| 5447 |
programs in this API. |
| 5448 |
|
| 5449 |
The installed calls and feature_indication members provide the |
| 5450 |
installed UV calls and the UV's other feature indications. |
| 5451 |
|
| 5452 |
The max_* members provide information about the maximum number of PV |
| 5453 |
vcpus, PV guests and PV guest memory size. |
| 5454 |
|
| 5455 |
:: |
| 5456 |
|
| 5457 |
struct kvm_s390_pv_info_vm { |
| 5458 |
__u64 inst_calls_list[4]; |
| 5459 |
__u64 max_cpus; |
| 5460 |
__u64 max_guests; |
| 5461 |
__u64 max_guest_addr; |
| 5462 |
__u64 feature_indication; |
| 5463 |
}; |
| 5464 |
|
| 5465 |
|
| 5466 |
KVM_PV_INFO_DUMP |
| 5467 |
This subcommand provides information related to dumping PV guests. |
| 5468 |
|
| 5469 |
:: |
| 5470 |
|
| 5471 |
struct kvm_s390_pv_info_dump { |
| 5472 |
__u64 dump_cpu_buffer_len; |
| 5473 |
__u64 dump_config_mem_buffer_per_1m; |
| 5474 |
__u64 dump_config_finalize_len; |
| 5475 |
}; |
| 5476 |
|
| 5477 |
KVM_PV_DUMP |
| 5478 |
:Capability: KVM_CAP_S390_PROTECTED_DUMP |
| 5479 |
|
| 5480 |
Presents an API that provides calls which facilitate dumping a |
| 5481 |
protected VM. |
| 5482 |
|
| 5483 |
:: |
| 5484 |
|
| 5485 |
struct kvm_s390_pv_dmp { |
| 5486 |
__u64 subcmd; |
| 5487 |
__u64 buff_addr; |
| 5488 |
__u64 buff_len; |
| 5489 |
__u64 gaddr; /* For dump storage state */ |
| 5490 |
}; |
| 5491 |
|
| 5492 |
**subcommands:** |
| 5493 |
|
| 5494 |
KVM_PV_DUMP_INIT |
| 5495 |
Initializes the dump process of a protected VM. If this call does |
| 5496 |
not succeed all other subcommands will fail with -EINVAL. This |
| 5497 |
subcommand will return -EINVAL if a dump process has not yet been |
| 5498 |
completed. |
| 5499 |
|
| 5500 |
Not all PV vms can be dumped, the owner needs to set `dump |
| 5501 |
allowed` PCF bit 34 in the SE header to allow dumping. |
| 5502 |
|
| 5503 |
KVM_PV_DUMP_CONFIG_STOR_STATE |
| 5504 |
Stores `buff_len` bytes of tweak component values starting with |
| 5505 |
the 1MB block specified by the absolute guest address |
| 5506 |
(`gaddr`). `buff_len` needs to be `conf_dump_storage_state_len` |
| 5507 |
aligned and at least >= the `conf_dump_storage_state_len` value |
| 5508 |
provided by the dump uv_info data. buff_user might be written to |
| 5509 |
even if an error rc is returned. For instance if we encounter a |
| 5510 |
fault after writing the first page of data. |
| 5511 |
|
| 5512 |
KVM_PV_DUMP_COMPLETE |
| 5513 |
If the subcommand succeeds it completes the dump process and lets |
| 5514 |
KVM_PV_DUMP_INIT be called again. |
| 5515 |
|
| 5516 |
On success `conf_dump_finalize_len` bytes of completion data will be |
| 5517 |
stored to the `buff_addr`. The completion data contains a key |
| 5518 |
derivation seed, IV, tweak nonce and encryption keys as well as an |
| 5519 |
authentication tag all of which are needed to decrypt the dump at a |
| 5520 |
later time. |
| 5521 |
|
| 5522 |
KVM_PV_ASYNC_CLEANUP_PREPARE |
| 5523 |
:Capability: KVM_CAP_S390_PROTECTED_ASYNC_DISABLE |
| 5524 |
|
| 5525 |
Prepare the current protected VM for asynchronous teardown. Most |
| 5526 |
resources used by the current protected VM will be set aside for a |
| 5527 |
subsequent asynchronous teardown. The current protected VM will then |
| 5528 |
resume execution immediately as non-protected. There can be at most |
| 5529 |
one protected VM prepared for asynchronous teardown at any time. If |
| 5530 |
a protected VM had already been prepared for teardown without |
| 5531 |
subsequently calling KVM_PV_ASYNC_CLEANUP_PERFORM, this call will |
| 5532 |
fail. In that case, the userspace process should issue a normal |
| 5533 |
KVM_PV_DISABLE. The resources set aside with this call will need to |
| 5534 |
be cleaned up with a subsequent call to KVM_PV_ASYNC_CLEANUP_PERFORM |
| 5535 |
or KVM_PV_DISABLE, otherwise they will be cleaned up when KVM |
| 5536 |
terminates. KVM_PV_ASYNC_CLEANUP_PREPARE can be called again as soon |
| 5537 |
as cleanup starts, i.e. before KVM_PV_ASYNC_CLEANUP_PERFORM finishes. |
| 5538 |
|
| 5539 |
KVM_PV_ASYNC_CLEANUP_PERFORM |
| 5540 |
:Capability: KVM_CAP_S390_PROTECTED_ASYNC_DISABLE |
| 5541 |
|
| 5542 |
Tear down the protected VM previously prepared for teardown with |
| 5543 |
KVM_PV_ASYNC_CLEANUP_PREPARE. The resources that had been set aside |
| 5544 |
will be freed during the execution of this command. This PV command |
| 5545 |
should ideally be issued by userspace from a separate thread. If a |
| 5546 |
fatal signal is received (or the process terminates naturally), the |
| 5547 |
command will terminate immediately without completing, and the normal |
| 5548 |
KVM shutdown procedure will take care of cleaning up all remaining |
| 5549 |
protected VMs, including the ones whose teardown was interrupted by |
| 5550 |
process termination. |
| 5551 |
|
| 5552 |
4.126 KVM_XEN_HVM_SET_ATTR |
| 5553 |
-------------------------- |
| 5554 |
|
| 5555 |
:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO |
| 5556 |
:Architectures: x86 |
| 5557 |
:Type: vm ioctl |
| 5558 |
:Parameters: struct kvm_xen_hvm_attr |
| 5559 |
:Returns: 0 on success, < 0 on error |
| 5560 |
|
| 5561 |
:: |
| 5562 |
|
| 5563 |
struct kvm_xen_hvm_attr { |
| 5564 |
__u16 type; |
| 5565 |
__u16 pad[3]; |
| 5566 |
union { |
| 5567 |
__u8 long_mode; |
| 5568 |
__u8 vector; |
| 5569 |
__u8 runstate_update_flag; |
| 5570 |
union { |
| 5571 |
__u64 gfn; |
| 5572 |
__u64 hva; |
| 5573 |
} shared_info; |
| 5574 |
struct { |
| 5575 |
__u32 send_port; |
| 5576 |
__u32 type; /* EVTCHNSTAT_ipi / EVTCHNSTAT_interdomain */ |
| 5577 |
__u32 flags; |
| 5578 |
union { |
| 5579 |
struct { |
| 5580 |
__u32 port; |
| 5581 |
__u32 vcpu; |
| 5582 |
__u32 priority; |
| 5583 |
} port; |
| 5584 |
struct { |
| 5585 |
__u32 port; /* Zero for eventfd */ |
| 5586 |
__s32 fd; |
| 5587 |
} eventfd; |
| 5588 |
__u32 padding[4]; |
| 5589 |
} deliver; |
| 5590 |
} evtchn; |
| 5591 |
__u32 xen_version; |
| 5592 |
__u64 pad[8]; |
| 5593 |
} u; |
| 5594 |
}; |
| 5595 |
|
| 5596 |
type values: |
| 5597 |
|
| 5598 |
KVM_XEN_ATTR_TYPE_LONG_MODE |
| 5599 |
Sets the ABI mode of the VM to 32-bit or 64-bit (long mode). This |
| 5600 |
determines the layout of the shared_info page exposed to the VM. |
| 5601 |
|
| 5602 |
KVM_XEN_ATTR_TYPE_SHARED_INFO |
| 5603 |
Sets the guest physical frame number at which the Xen shared_info |
| 5604 |
page resides. Note that although Xen places vcpu_info for the first |
| 5605 |
32 vCPUs in the shared_info page, KVM does not automatically do so |
| 5606 |
and instead requires that KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO or |
| 5607 |
KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO_HVA be used explicitly even when |
| 5608 |
the vcpu_info for a given vCPU resides at the "default" location |
| 5609 |
in the shared_info page. This is because KVM may not be aware of |
| 5610 |
the Xen CPU id which is used as the index into the vcpu_info[] |
| 5611 |
array, so may know the correct default location. |
| 5612 |
|
| 5613 |
Note that the shared_info page may be constantly written to by KVM; |
| 5614 |
it contains the event channel bitmap used to deliver interrupts to |
| 5615 |
a Xen guest, amongst other things. It is exempt from dirty tracking |
| 5616 |
mechanisms — KVM will not explicitly mark the page as dirty each |
| 5617 |
time an event channel interrupt is delivered to the guest! Thus, |
| 5618 |
userspace should always assume that the designated GFN is dirty if |
| 5619 |
any vCPU has been running or any event channel interrupts can be |
| 5620 |
routed to the guest. |
| 5621 |
|
| 5622 |
Setting the gfn to KVM_XEN_INVALID_GFN will disable the shared_info |
| 5623 |
page. |
| 5624 |
|
| 5625 |
KVM_XEN_ATTR_TYPE_SHARED_INFO_HVA |
| 5626 |
If the KVM_XEN_HVM_CONFIG_SHARED_INFO_HVA flag is also set in the |
| 5627 |
Xen capabilities, then this attribute may be used to set the |
| 5628 |
userspace address at which the shared_info page resides, which |
| 5629 |
will always be fixed in the VMM regardless of where it is mapped |
| 5630 |
in guest physical address space. This attribute should be used in |
| 5631 |
preference to KVM_XEN_ATTR_TYPE_SHARED_INFO as it avoids |
| 5632 |
unnecessary invalidation of an internal cache when the page is |
| 5633 |
re-mapped in guest physical address space. |
| 5634 |
|
| 5635 |
Setting the hva to zero will disable the shared_info page. |
| 5636 |
|
| 5637 |
KVM_XEN_ATTR_TYPE_UPCALL_VECTOR |
| 5638 |
Sets the exception vector used to deliver Xen event channel upcalls. |
| 5639 |
This is the HVM-wide vector injected directly by the hypervisor |
| 5640 |
(not through the local APIC), typically configured by a guest via |
| 5641 |
HVM_PARAM_CALLBACK_IRQ. This can be disabled again (e.g. for guest |
| 5642 |
SHUTDOWN_soft_reset) by setting it to zero. |
| 5643 |
|
| 5644 |
KVM_XEN_ATTR_TYPE_EVTCHN |
| 5645 |
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates |
| 5646 |
support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It configures |
| 5647 |
an outbound port number for interception of EVTCHNOP_send requests |
| 5648 |
from the guest. A given sending port number may be directed back to |
| 5649 |
a specified vCPU (by APIC ID) / port / priority on the guest, or to |
| 5650 |
trigger events on an eventfd. The vCPU and priority can be changed |
| 5651 |
by setting KVM_XEN_EVTCHN_UPDATE in a subsequent call, but other |
| 5652 |
fields cannot change for a given sending port. A port mapping is |
| 5653 |
removed by using KVM_XEN_EVTCHN_DEASSIGN in the flags field. Passing |
| 5654 |
KVM_XEN_EVTCHN_RESET in the flags field removes all interception of |
| 5655 |
outbound event channels. The values of the flags field are mutually |
| 5656 |
exclusive and cannot be combined as a bitmask. |
| 5657 |
|
| 5658 |
KVM_XEN_ATTR_TYPE_XEN_VERSION |
| 5659 |
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates |
| 5660 |
support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It configures |
| 5661 |
the 32-bit version code returned to the guest when it invokes the |
| 5662 |
XENVER_version call; typically (XEN_MAJOR << 16 | XEN_MINOR). PV |
| 5663 |
Xen guests will often use this to as a dummy hypercall to trigger |
| 5664 |
event channel delivery, so responding within the kernel without |
| 5665 |
exiting to userspace is beneficial. |
| 5666 |
|
| 5667 |
KVM_XEN_ATTR_TYPE_RUNSTATE_UPDATE_FLAG |
| 5668 |
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates |
| 5669 |
support for KVM_XEN_HVM_CONFIG_RUNSTATE_UPDATE_FLAG. It enables the |
| 5670 |
XEN_RUNSTATE_UPDATE flag which allows guest vCPUs to safely read |
| 5671 |
other vCPUs' vcpu_runstate_info. Xen guests enable this feature via |
| 5672 |
the VMASST_TYPE_runstate_update_flag of the HYPERVISOR_vm_assist |
| 5673 |
hypercall. |
| 5674 |
|
| 5675 |
4.127 KVM_XEN_HVM_GET_ATTR |
| 5676 |
-------------------------- |
| 5677 |
|
| 5678 |
:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO |
| 5679 |
:Architectures: x86 |
| 5680 |
:Type: vm ioctl |
| 5681 |
:Parameters: struct kvm_xen_hvm_attr |
| 5682 |
:Returns: 0 on success, < 0 on error |
| 5683 |
|
| 5684 |
Allows Xen VM attributes to be read. For the structure and types, |
| 5685 |
see KVM_XEN_HVM_SET_ATTR above. The KVM_XEN_ATTR_TYPE_EVTCHN |
| 5686 |
attribute cannot be read. |
| 5687 |
|
| 5688 |
4.128 KVM_XEN_VCPU_SET_ATTR |
| 5689 |
--------------------------- |
| 5690 |
|
| 5691 |
:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO |
| 5692 |
:Architectures: x86 |
| 5693 |
:Type: vcpu ioctl |
| 5694 |
:Parameters: struct kvm_xen_vcpu_attr |
| 5695 |
:Returns: 0 on success, < 0 on error |
| 5696 |
|
| 5697 |
:: |
| 5698 |
|
| 5699 |
struct kvm_xen_vcpu_attr { |
| 5700 |
__u16 type; |
| 5701 |
__u16 pad[3]; |
| 5702 |
union { |
| 5703 |
__u64 gpa; |
| 5704 |
__u64 pad[4]; |
| 5705 |
struct { |
| 5706 |
__u64 state; |
| 5707 |
__u64 state_entry_time; |
| 5708 |
__u64 time_running; |
| 5709 |
__u64 time_runnable; |
| 5710 |
__u64 time_blocked; |
| 5711 |
__u64 time_offline; |
| 5712 |
} runstate; |
| 5713 |
__u32 vcpu_id; |
| 5714 |
struct { |
| 5715 |
__u32 port; |
| 5716 |
__u32 priority; |
| 5717 |
__u64 expires_ns; |
| 5718 |
} timer; |
| 5719 |
__u8 vector; |
| 5720 |
} u; |
| 5721 |
}; |
| 5722 |
|
| 5723 |
type values: |
| 5724 |
|
| 5725 |
KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO |
| 5726 |
Sets the guest physical address of the vcpu_info for a given vCPU. |
| 5727 |
As with the shared_info page for the VM, the corresponding page may be |
| 5728 |
dirtied at any time if event channel interrupt delivery is enabled, so |
| 5729 |
userspace should always assume that the page is dirty without relying |
| 5730 |
on dirty logging. Setting the gpa to KVM_XEN_INVALID_GPA will disable |
| 5731 |
the vcpu_info. |
| 5732 |
|
| 5733 |
KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO_HVA |
| 5734 |
If the KVM_XEN_HVM_CONFIG_SHARED_INFO_HVA flag is also set in the |
| 5735 |
Xen capabilities, then this attribute may be used to set the |
| 5736 |
userspace address of the vcpu_info for a given vCPU. It should |
| 5737 |
only be used when the vcpu_info resides at the "default" location |
| 5738 |
in the shared_info page. In this case it is safe to assume the |
| 5739 |
userspace address will not change, because the shared_info page is |
| 5740 |
an overlay on guest memory and remains at a fixed host address |
| 5741 |
regardless of where it is mapped in guest physical address space |
| 5742 |
and hence unnecessary invalidation of an internal cache may be |
| 5743 |
avoided if the guest memory layout is modified. |
| 5744 |
If the vcpu_info does not reside at the "default" location then |
| 5745 |
it is not guaranteed to remain at the same host address and |
| 5746 |
hence the aforementioned cache invalidation is required. |
| 5747 |
|
| 5748 |
KVM_XEN_VCPU_ATTR_TYPE_VCPU_TIME_INFO |
| 5749 |
Sets the guest physical address of an additional pvclock structure |
| 5750 |
for a given vCPU. This is typically used for guest vsyscall support. |
| 5751 |
Setting the gpa to KVM_XEN_INVALID_GPA will disable the structure. |
| 5752 |
|
| 5753 |
KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADDR |
| 5754 |
Sets the guest physical address of the vcpu_runstate_info for a given |
| 5755 |
vCPU. This is how a Xen guest tracks CPU state such as steal time. |
| 5756 |
Setting the gpa to KVM_XEN_INVALID_GPA will disable the runstate area. |
| 5757 |
|
| 5758 |
KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_CURRENT |
| 5759 |
Sets the runstate (RUNSTATE_running/_runnable/_blocked/_offline) of |
| 5760 |
the given vCPU from the .u.runstate.state member of the structure. |
| 5761 |
KVM automatically accounts running and runnable time but blocked |
| 5762 |
and offline states are only entered explicitly. |
| 5763 |
|
| 5764 |
KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_DATA |
| 5765 |
Sets all fields of the vCPU runstate data from the .u.runstate member |
| 5766 |
of the structure, including the current runstate. The state_entry_time |
| 5767 |
must equal the sum of the other four times. |
| 5768 |
|
| 5769 |
KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADJUST |
| 5770 |
This *adds* the contents of the .u.runstate members of the structure |
| 5771 |
to the corresponding members of the given vCPU's runstate data, thus |
| 5772 |
permitting atomic adjustments to the runstate times. The adjustment |
| 5773 |
to the state_entry_time must equal the sum of the adjustments to the |
| 5774 |
other four times. The state field must be set to -1, or to a valid |
| 5775 |
runstate value (RUNSTATE_running, RUNSTATE_runnable, RUNSTATE_blocked |
| 5776 |
or RUNSTATE_offline) to set the current accounted state as of the |
| 5777 |
adjusted state_entry_time. |
| 5778 |
|
| 5779 |
KVM_XEN_VCPU_ATTR_TYPE_VCPU_ID |
| 5780 |
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates |
| 5781 |
support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It sets the Xen |
| 5782 |
vCPU ID of the given vCPU, to allow timer-related VCPU operations to |
| 5783 |
be intercepted by KVM. |
| 5784 |
|
| 5785 |
KVM_XEN_VCPU_ATTR_TYPE_TIMER |
| 5786 |
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates |
| 5787 |
support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It sets the |
| 5788 |
event channel port/priority for the VIRQ_TIMER of the vCPU, as well |
| 5789 |
as allowing a pending timer to be saved/restored. Setting the timer |
| 5790 |
port to zero disables kernel handling of the singleshot timer. |
| 5791 |
|
| 5792 |
KVM_XEN_VCPU_ATTR_TYPE_UPCALL_VECTOR |
| 5793 |
This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates |
| 5794 |
support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It sets the |
| 5795 |
per-vCPU local APIC upcall vector, configured by a Xen guest with |
| 5796 |
the HVMOP_set_evtchn_upcall_vector hypercall. This is typically |
| 5797 |
used by Windows guests, and is distinct from the HVM-wide upcall |
| 5798 |
vector configured with HVM_PARAM_CALLBACK_IRQ. It is disabled by |
| 5799 |
setting the vector to zero. |
| 5800 |
|
| 5801 |
|
| 5802 |
4.129 KVM_XEN_VCPU_GET_ATTR |
| 5803 |
--------------------------- |
| 5804 |
|
| 5805 |
:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_SHARED_INFO |
| 5806 |
:Architectures: x86 |
| 5807 |
:Type: vcpu ioctl |
| 5808 |
:Parameters: struct kvm_xen_vcpu_attr |
| 5809 |
:Returns: 0 on success, < 0 on error |
| 5810 |
|
| 5811 |
Allows Xen vCPU attributes to be read. For the structure and types, |
| 5812 |
see KVM_XEN_VCPU_SET_ATTR above. |
| 5813 |
|
| 5814 |
The KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADJUST type may not be used |
| 5815 |
with the KVM_XEN_VCPU_GET_ATTR ioctl. |
| 5816 |
|
| 5817 |
4.130 KVM_ARM_MTE_COPY_TAGS |
| 5818 |
--------------------------- |
| 5819 |
|
| 5820 |
:Capability: KVM_CAP_ARM_MTE |
| 5821 |
:Architectures: arm64 |
| 5822 |
:Type: vm ioctl |
| 5823 |
:Parameters: struct kvm_arm_copy_mte_tags |
| 5824 |
:Returns: number of bytes copied, < 0 on error (-EINVAL for incorrect |
| 5825 |
arguments, -EFAULT if memory cannot be accessed). |
| 5826 |
|
| 5827 |
:: |
| 5828 |
|
| 5829 |
struct kvm_arm_copy_mte_tags { |
| 5830 |
__u64 guest_ipa; |
| 5831 |
__u64 length; |
| 5832 |
void __user *addr; |
| 5833 |
__u64 flags; |
| 5834 |
__u64 reserved[2]; |
| 5835 |
}; |
| 5836 |
|
| 5837 |
Copies Memory Tagging Extension (MTE) tags to/from guest tag memory. The |
| 5838 |
``guest_ipa`` and ``length`` fields must be ``PAGE_SIZE`` aligned. |
| 5839 |
``length`` must not be bigger than 2^31 - PAGE_SIZE bytes. The ``addr`` |
| 5840 |
field must point to a buffer which the tags will be copied to or from. |
| 5841 |
|
| 5842 |
``flags`` specifies the direction of copy, either ``KVM_ARM_TAGS_TO_GUEST`` or |
| 5843 |
``KVM_ARM_TAGS_FROM_GUEST``. |
| 5844 |
|
| 5845 |
The size of the buffer to store the tags is ``(length / 16)`` bytes |
| 5846 |
(granules in MTE are 16 bytes long). Each byte contains a single tag |
| 5847 |
value. This matches the format of ``PTRACE_PEEKMTETAGS`` and |
| 5848 |
``PTRACE_POKEMTETAGS``. |
| 5849 |
|
| 5850 |
If an error occurs before any data is copied then a negative error code is |
| 5851 |
returned. If some tags have been copied before an error occurs then the number |
| 5852 |
of bytes successfully copied is returned. If the call completes successfully |
| 5853 |
then ``length`` is returned. |
| 5854 |
|
| 5855 |
4.131 KVM_GET_SREGS2 |
| 5856 |
-------------------- |
| 5857 |
|
| 5858 |
:Capability: KVM_CAP_SREGS2 |
| 5859 |
:Architectures: x86 |
| 5860 |
:Type: vcpu ioctl |
| 5861 |
:Parameters: struct kvm_sregs2 (out) |
| 5862 |
:Returns: 0 on success, -1 on error |
| 5863 |
|
| 5864 |
Reads special registers from the vcpu. |
| 5865 |
This ioctl (when supported) replaces the KVM_GET_SREGS. |
| 5866 |
|
| 5867 |
:: |
| 5868 |
|
| 5869 |
struct kvm_sregs2 { |
| 5870 |
/* out (KVM_GET_SREGS2) / in (KVM_SET_SREGS2) */ |
| 5871 |
struct kvm_segment cs, ds, es, fs, gs, ss; |
| 5872 |
struct kvm_segment tr, ldt; |
| 5873 |
struct kvm_dtable gdt, idt; |
| 5874 |
__u64 cr0, cr2, cr3, cr4, cr8; |
| 5875 |
__u64 efer; |
| 5876 |
__u64 apic_base; |
| 5877 |
__u64 flags; |
| 5878 |
__u64 pdptrs[4]; |
| 5879 |
}; |
| 5880 |
|
| 5881 |
flags values for ``kvm_sregs2``: |
| 5882 |
|
| 5883 |
``KVM_SREGS2_FLAGS_PDPTRS_VALID`` |
| 5884 |
|
| 5885 |
Indicates that the struct contains valid PDPTR values. |
| 5886 |
|
| 5887 |
|
| 5888 |
4.132 KVM_SET_SREGS2 |
| 5889 |
-------------------- |
| 5890 |
|
| 5891 |
:Capability: KVM_CAP_SREGS2 |
| 5892 |
:Architectures: x86 |
| 5893 |
:Type: vcpu ioctl |
| 5894 |
:Parameters: struct kvm_sregs2 (in) |
| 5895 |
:Returns: 0 on success, -1 on error |
| 5896 |
|
| 5897 |
Writes special registers into the vcpu. |
| 5898 |
See KVM_GET_SREGS2 for the data structures. |
| 5899 |
This ioctl (when supported) replaces the KVM_SET_SREGS. |
| 5900 |
|
| 5901 |
4.133 KVM_GET_STATS_FD |
| 5902 |
---------------------- |
| 5903 |
|
| 5904 |
:Capability: KVM_CAP_STATS_BINARY_FD |
| 5905 |
:Architectures: all |
| 5906 |
:Type: vm ioctl, vcpu ioctl |
| 5907 |
:Parameters: none |
| 5908 |
:Returns: statistics file descriptor on success, < 0 on error |
| 5909 |
|
| 5910 |
Errors: |
| 5911 |
|
| 5912 |
====== ====================================================== |
| 5913 |
ENOMEM if the fd could not be created due to lack of memory |
| 5914 |
EMFILE if the number of opened files exceeds the limit |
| 5915 |
====== ====================================================== |
| 5916 |
|
| 5917 |
The returned file descriptor can be used to read VM/vCPU statistics data in |
| 5918 |
binary format. The data in the file descriptor consists of four blocks |
| 5919 |
organized as follows: |
| 5920 |
|
| 5921 |
+-------------+ |
| 5922 |
| Header | |
| 5923 |
+-------------+ |
| 5924 |
| id string | |
| 5925 |
+-------------+ |
| 5926 |
| Descriptors | |
| 5927 |
+-------------+ |
| 5928 |
| Stats Data | |
| 5929 |
+-------------+ |
| 5930 |
|
| 5931 |
Apart from the header starting at offset 0, please be aware that it is |
| 5932 |
not guaranteed that the four blocks are adjacent or in the above order; |
| 5933 |
the offsets of the id, descriptors and data blocks are found in the |
| 5934 |
header. However, all four blocks are aligned to 64 bit offsets in the |
| 5935 |
file and they do not overlap. |
| 5936 |
|
| 5937 |
All blocks except the data block are immutable. Userspace can read them |
| 5938 |
only one time after retrieving the file descriptor, and then use ``pread`` or |
| 5939 |
``lseek`` to read the statistics repeatedly. |
| 5940 |
|
| 5941 |
All data is in system endianness. |
| 5942 |
|
| 5943 |
The format of the header is as follows:: |
| 5944 |
|
| 5945 |
struct kvm_stats_header { |
| 5946 |
__u32 flags; |
| 5947 |
__u32 name_size; |
| 5948 |
__u32 num_desc; |
| 5949 |
__u32 id_offset; |
| 5950 |
__u32 desc_offset; |
| 5951 |
__u32 data_offset; |
| 5952 |
}; |
| 5953 |
|
| 5954 |
The ``flags`` field is not used at the moment. It is always read as 0. |
| 5955 |
|
| 5956 |
The ``name_size`` field is the size (in byte) of the statistics name string |
| 5957 |
(including trailing '\0') which is contained in the "id string" block and |
| 5958 |
appended at the end of every descriptor. |
| 5959 |
|
| 5960 |
The ``num_desc`` field is the number of descriptors that are included in the |
| 5961 |
descriptor block. (The actual number of values in the data block may be |
| 5962 |
larger, since each descriptor may comprise more than one value). |
| 5963 |
|
| 5964 |
The ``id_offset`` field is the offset of the id string from the start of the |
| 5965 |
file indicated by the file descriptor. It is a multiple of 8. |
| 5966 |
|
| 5967 |
The ``desc_offset`` field is the offset of the Descriptors block from the start |
| 5968 |
of the file indicated by the file descriptor. It is a multiple of 8. |
| 5969 |
|
| 5970 |
The ``data_offset`` field is the offset of the Stats Data block from the start |
| 5971 |
of the file indicated by the file descriptor. It is a multiple of 8. |
| 5972 |
|
| 5973 |
The id string block contains a string which identifies the file descriptor on |
| 5974 |
which KVM_GET_STATS_FD was invoked. The size of the block, including the |
| 5975 |
trailing ``'\0'``, is indicated by the ``name_size`` field in the header. |
| 5976 |
|
| 5977 |
The descriptors block is only needed to be read once for the lifetime of the |
| 5978 |
file descriptor contains a sequence of ``struct kvm_stats_desc``, each followed |
| 5979 |
by a string of size ``name_size``. |
| 5980 |
:: |
| 5981 |
|
| 5982 |
#define KVM_STATS_TYPE_SHIFT 0 |
| 5983 |
#define KVM_STATS_TYPE_MASK (0xF << KVM_STATS_TYPE_SHIFT) |
| 5984 |
#define KVM_STATS_TYPE_CUMULATIVE (0x0 << KVM_STATS_TYPE_SHIFT) |
| 5985 |
#define KVM_STATS_TYPE_INSTANT (0x1 << KVM_STATS_TYPE_SHIFT) |
| 5986 |
#define KVM_STATS_TYPE_PEAK (0x2 << KVM_STATS_TYPE_SHIFT) |
| 5987 |
#define KVM_STATS_TYPE_LINEAR_HIST (0x3 << KVM_STATS_TYPE_SHIFT) |
| 5988 |
#define KVM_STATS_TYPE_LOG_HIST (0x4 << KVM_STATS_TYPE_SHIFT) |
| 5989 |
#define KVM_STATS_TYPE_MAX KVM_STATS_TYPE_LOG_HIST |
| 5990 |
|
| 5991 |
#define KVM_STATS_UNIT_SHIFT 4 |
| 5992 |
#define KVM_STATS_UNIT_MASK (0xF << KVM_STATS_UNIT_SHIFT) |
| 5993 |
#define KVM_STATS_UNIT_NONE (0x0 << KVM_STATS_UNIT_SHIFT) |
| 5994 |
#define KVM_STATS_UNIT_BYTES (0x1 << KVM_STATS_UNIT_SHIFT) |
| 5995 |
#define KVM_STATS_UNIT_SECONDS (0x2 << KVM_STATS_UNIT_SHIFT) |
| 5996 |
#define KVM_STATS_UNIT_CYCLES (0x3 << KVM_STATS_UNIT_SHIFT) |
| 5997 |
#define KVM_STATS_UNIT_BOOLEAN (0x4 << KVM_STATS_UNIT_SHIFT) |
| 5998 |
#define KVM_STATS_UNIT_MAX KVM_STATS_UNIT_BOOLEAN |
| 5999 |
|
| 6000 |
#define KVM_STATS_BASE_SHIFT 8 |
| 6001 |
#define KVM_STATS_BASE_MASK (0xF << KVM_STATS_BASE_SHIFT) |
| 6002 |
#define KVM_STATS_BASE_POW10 (0x0 << KVM_STATS_BASE_SHIFT) |
| 6003 |
#define KVM_STATS_BASE_POW2 (0x1 << KVM_STATS_BASE_SHIFT) |
| 6004 |
#define KVM_STATS_BASE_MAX KVM_STATS_BASE_POW2 |
| 6005 |
|
| 6006 |
struct kvm_stats_desc { |
| 6007 |
__u32 flags; |
| 6008 |
__s16 exponent; |
| 6009 |
__u16 size; |
| 6010 |
__u32 offset; |
| 6011 |
__u32 bucket_size; |
| 6012 |
char name[]; |
| 6013 |
}; |
| 6014 |
|
| 6015 |
The ``flags`` field contains the type and unit of the statistics data described |
| 6016 |
by this descriptor. Its endianness is CPU native. |
| 6017 |
The following flags are supported: |
| 6018 |
|
| 6019 |
Bits 0-3 of ``flags`` encode the type: |
| 6020 |
|
| 6021 |
* ``KVM_STATS_TYPE_CUMULATIVE`` |
| 6022 |
The statistics reports a cumulative count. The value of data can only be increased. |
| 6023 |
Most of the counters used in KVM are of this type. |
| 6024 |
The corresponding ``size`` field for this type is always 1. |
| 6025 |
All cumulative statistics data are read/write. |
| 6026 |
* ``KVM_STATS_TYPE_INSTANT`` |
| 6027 |
The statistics reports an instantaneous value. Its value can be increased or |
| 6028 |
decreased. This type is usually used as a measurement of some resources, |
| 6029 |
like the number of dirty pages, the number of large pages, etc. |
| 6030 |
All instant statistics are read only. |
| 6031 |
The corresponding ``size`` field for this type is always 1. |
| 6032 |
* ``KVM_STATS_TYPE_PEAK`` |
| 6033 |
The statistics data reports a peak value, for example the maximum number |
| 6034 |
of items in a hash table bucket, the longest time waited and so on. |
| 6035 |
The value of data can only be increased. |
| 6036 |
The corresponding ``size`` field for this type is always 1. |
| 6037 |
* ``KVM_STATS_TYPE_LINEAR_HIST`` |
| 6038 |
The statistic is reported as a linear histogram. The number of |
| 6039 |
buckets is specified by the ``size`` field. The size of buckets is specified |
| 6040 |
by the ``hist_param`` field. The range of the Nth bucket (1 <= N < ``size``) |
| 6041 |
is [``hist_param``*(N-1), ``hist_param``*N), while the range of the last |
| 6042 |
bucket is [``hist_param``*(``size``-1), +INF). (+INF means positive infinity |
| 6043 |
value.) |
| 6044 |
* ``KVM_STATS_TYPE_LOG_HIST`` |
| 6045 |
The statistic is reported as a logarithmic histogram. The number of |
| 6046 |
buckets is specified by the ``size`` field. The range of the first bucket is |
| 6047 |
[0, 1), while the range of the last bucket is [pow(2, ``size``-2), +INF). |
| 6048 |
Otherwise, The Nth bucket (1 < N < ``size``) covers |
| 6049 |
[pow(2, N-2), pow(2, N-1)). |
| 6050 |
|
| 6051 |
Bits 4-7 of ``flags`` encode the unit: |
| 6052 |
|
| 6053 |
* ``KVM_STATS_UNIT_NONE`` |
| 6054 |
There is no unit for the value of statistics data. This usually means that |
| 6055 |
the value is a simple counter of an event. |
| 6056 |
* ``KVM_STATS_UNIT_BYTES`` |
| 6057 |
It indicates that the statistics data is used to measure memory size, in the |
| 6058 |
unit of Byte, KiByte, MiByte, GiByte, etc. The unit of the data is |
| 6059 |
determined by the ``exponent`` field in the descriptor. |
| 6060 |
* ``KVM_STATS_UNIT_SECONDS`` |
| 6061 |
It indicates that the statistics data is used to measure time or latency. |
| 6062 |
* ``KVM_STATS_UNIT_CYCLES`` |
| 6063 |
It indicates that the statistics data is used to measure CPU clock cycles. |
| 6064 |
* ``KVM_STATS_UNIT_BOOLEAN`` |
| 6065 |
It indicates that the statistic will always be either 0 or 1. Boolean |
| 6066 |
statistics of "peak" type will never go back from 1 to 0. Boolean |
| 6067 |
statistics can be linear histograms (with two buckets) but not logarithmic |
| 6068 |
histograms. |
| 6069 |
|
| 6070 |
Note that, in the case of histograms, the unit applies to the bucket |
| 6071 |
ranges, while the bucket value indicates how many samples fell in the |
| 6072 |
bucket's range. |
| 6073 |
|
| 6074 |
Bits 8-11 of ``flags``, together with ``exponent``, encode the scale of the |
| 6075 |
unit: |
| 6076 |
|
| 6077 |
* ``KVM_STATS_BASE_POW10`` |
| 6078 |
The scale is based on power of 10. It is used for measurement of time and |
| 6079 |
CPU clock cycles. For example, an exponent of -9 can be used with |
| 6080 |
``KVM_STATS_UNIT_SECONDS`` to express that the unit is nanoseconds. |
| 6081 |
* ``KVM_STATS_BASE_POW2`` |
| 6082 |
The scale is based on power of 2. It is used for measurement of memory size. |
| 6083 |
For example, an exponent of 20 can be used with ``KVM_STATS_UNIT_BYTES`` to |
| 6084 |
express that the unit is MiB. |
| 6085 |
|
| 6086 |
The ``size`` field is the number of values of this statistics data. Its |
| 6087 |
value is usually 1 for most of simple statistics. 1 means it contains an |
| 6088 |
unsigned 64bit data. |
| 6089 |
|
| 6090 |
The ``offset`` field is the offset from the start of Data Block to the start of |
| 6091 |
the corresponding statistics data. |
| 6092 |
|
| 6093 |
The ``bucket_size`` field is used as a parameter for histogram statistics data. |
| 6094 |
It is only used by linear histogram statistics data, specifying the size of a |
| 6095 |
bucket in the unit expressed by bits 4-11 of ``flags`` together with ``exponent``. |
| 6096 |
|
| 6097 |
The ``name`` field is the name string of the statistics data. The name string |
| 6098 |
starts at the end of ``struct kvm_stats_desc``. The maximum length including |
| 6099 |
the trailing ``'\0'``, is indicated by ``name_size`` in the header. |
| 6100 |
|
| 6101 |
The Stats Data block contains an array of 64-bit values in the same order |
| 6102 |
as the descriptors in Descriptors block. |
| 6103 |
|
| 6104 |
4.134 KVM_GET_XSAVE2 |
| 6105 |
-------------------- |
| 6106 |
|
| 6107 |
:Capability: KVM_CAP_XSAVE2 |
| 6108 |
:Architectures: x86 |
| 6109 |
:Type: vcpu ioctl |
| 6110 |
:Parameters: struct kvm_xsave (out) |
| 6111 |
:Returns: 0 on success, -1 on error |
| 6112 |
|
| 6113 |
|
| 6114 |
:: |
| 6115 |
|
| 6116 |
struct kvm_xsave { |
| 6117 |
__u32 region[1024]; |
| 6118 |
__u32 extra[0]; |
| 6119 |
}; |
| 6120 |
|
| 6121 |
This ioctl would copy current vcpu's xsave struct to the userspace. It |
| 6122 |
copies as many bytes as are returned by KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2) |
| 6123 |
when invoked on the vm file descriptor. The size value returned by |
| 6124 |
KVM_CHECK_EXTENSION(KVM_CAP_XSAVE2) will always be at least 4096. |
| 6125 |
Currently, it is only greater than 4096 if a dynamic feature has been |
| 6126 |
enabled with ``arch_prctl()``, but this may change in the future. |
| 6127 |
|
| 6128 |
The offsets of the state save areas in struct kvm_xsave follow the contents |
| 6129 |
of CPUID leaf 0xD on the host. |
| 6130 |
|
| 6131 |
4.135 KVM_XEN_HVM_EVTCHN_SEND |
| 6132 |
----------------------------- |
| 6133 |
|
| 6134 |
:Capability: KVM_CAP_XEN_HVM / KVM_XEN_HVM_CONFIG_EVTCHN_SEND |
| 6135 |
:Architectures: x86 |
| 6136 |
:Type: vm ioctl |
| 6137 |
:Parameters: struct kvm_irq_routing_xen_evtchn |
| 6138 |
:Returns: 0 on success, < 0 on error |
| 6139 |
|
| 6140 |
|
| 6141 |
:: |
| 6142 |
|
| 6143 |
struct kvm_irq_routing_xen_evtchn { |
| 6144 |
__u32 port; |
| 6145 |
__u32 vcpu; |
| 6146 |
__u32 priority; |
| 6147 |
}; |
| 6148 |
|
| 6149 |
This ioctl injects an event channel interrupt directly to the guest vCPU. |
| 6150 |
|
| 6151 |
4.136 KVM_S390_PV_CPU_COMMAND |
| 6152 |
----------------------------- |
| 6153 |
|
| 6154 |
:Capability: KVM_CAP_S390_PROTECTED_DUMP |
| 6155 |
:Architectures: s390 |
| 6156 |
:Type: vcpu ioctl |
| 6157 |
:Parameters: none |
| 6158 |
:Returns: 0 on success, < 0 on error |
| 6159 |
|
| 6160 |
This ioctl closely mirrors `KVM_S390_PV_COMMAND` but handles requests |
| 6161 |
for vcpus. It re-uses the kvm_s390_pv_dmp struct and hence also shares |
| 6162 |
the command ids. |
| 6163 |
|
| 6164 |
**command:** |
| 6165 |
|
| 6166 |
KVM_PV_DUMP |
| 6167 |
Presents an API that provides calls which facilitate dumping a vcpu |
| 6168 |
of a protected VM. |
| 6169 |
|
| 6170 |
**subcommand:** |
| 6171 |
|
| 6172 |
KVM_PV_DUMP_CPU |
| 6173 |
Provides encrypted dump data like register values. |
| 6174 |
The length of the returned data is provided by uv_info.guest_cpu_stor_len. |
| 6175 |
|
| 6176 |
4.137 KVM_S390_ZPCI_OP |
| 6177 |
---------------------- |
| 6178 |
|
| 6179 |
:Capability: KVM_CAP_S390_ZPCI_OP |
| 6180 |
:Architectures: s390 |
| 6181 |
:Type: vm ioctl |
| 6182 |
:Parameters: struct kvm_s390_zpci_op (in) |
| 6183 |
:Returns: 0 on success, <0 on error |
| 6184 |
|
| 6185 |
Used to manage hardware-assisted virtualization features for zPCI devices. |
| 6186 |
|
| 6187 |
Parameters are specified via the following structure:: |
| 6188 |
|
| 6189 |
struct kvm_s390_zpci_op { |
| 6190 |
/* in */ |
| 6191 |
__u32 fh; /* target device */ |
| 6192 |
__u8 op; /* operation to perform */ |
| 6193 |
__u8 pad[3]; |
| 6194 |
union { |
| 6195 |
/* for KVM_S390_ZPCIOP_REG_AEN */ |
| 6196 |
struct { |
| 6197 |
__u64 ibv; /* Guest addr of interrupt bit vector */ |
| 6198 |
__u64 sb; /* Guest addr of summary bit */ |
| 6199 |
__u32 flags; |
| 6200 |
__u32 noi; /* Number of interrupts */ |
| 6201 |
__u8 isc; /* Guest interrupt subclass */ |
| 6202 |
__u8 sbo; /* Offset of guest summary bit vector */ |
| 6203 |
__u16 pad; |
| 6204 |
} reg_aen; |
| 6205 |
__u64 reserved[8]; |
| 6206 |
} u; |
| 6207 |
}; |
| 6208 |
|
| 6209 |
The type of operation is specified in the "op" field. |
| 6210 |
KVM_S390_ZPCIOP_REG_AEN is used to register the VM for adapter event |
| 6211 |
notification interpretation, which will allow firmware delivery of adapter |
| 6212 |
events directly to the vm, with KVM providing a backup delivery mechanism; |
| 6213 |
KVM_S390_ZPCIOP_DEREG_AEN is used to subsequently disable interpretation of |
| 6214 |
adapter event notifications. |
| 6215 |
|
| 6216 |
The target zPCI function must also be specified via the "fh" field. For the |
| 6217 |
KVM_S390_ZPCIOP_REG_AEN operation, additional information to establish firmware |
| 6218 |
delivery must be provided via the "reg_aen" struct. |
| 6219 |
|
| 6220 |
The "pad" and "reserved" fields may be used for future extensions and should be |
| 6221 |
set to 0s by userspace. |
| 6222 |
|
| 6223 |
4.138 KVM_ARM_SET_COUNTER_OFFSET |
| 6224 |
-------------------------------- |
| 6225 |
|
| 6226 |
:Capability: KVM_CAP_COUNTER_OFFSET |
| 6227 |
:Architectures: arm64 |
| 6228 |
:Type: vm ioctl |
| 6229 |
:Parameters: struct kvm_arm_counter_offset (in) |
| 6230 |
:Returns: 0 on success, < 0 on error |
| 6231 |
|
| 6232 |
This capability indicates that userspace is able to apply a single VM-wide |
| 6233 |
offset to both the virtual and physical counters as viewed by the guest |
| 6234 |
using the KVM_ARM_SET_CNT_OFFSET ioctl and the following data structure: |
| 6235 |
|
| 6236 |
:: |
| 6237 |
|
| 6238 |
struct kvm_arm_counter_offset { |
| 6239 |
__u64 counter_offset; |
| 6240 |
__u64 reserved; |
| 6241 |
}; |
| 6242 |
|
| 6243 |
The offset describes a number of counter cycles that are subtracted from |
| 6244 |
both virtual and physical counter views (similar to the effects of the |
| 6245 |
CNTVOFF_EL2 and CNTPOFF_EL2 system registers, but only global). The offset |
| 6246 |
always applies to all vcpus (already created or created after this ioctl) |
| 6247 |
for this VM. |
| 6248 |
|
| 6249 |
It is userspace's responsibility to compute the offset based, for example, |
| 6250 |
on previous values of the guest counters. |
| 6251 |
|
| 6252 |
Any value other than 0 for the "reserved" field may result in an error |
| 6253 |
(-EINVAL) being returned. This ioctl can also return -EBUSY if any vcpu |
| 6254 |
ioctl is issued concurrently. |
| 6255 |
|
| 6256 |
Note that using this ioctl results in KVM ignoring subsequent userspace |
| 6257 |
writes to the CNTVCT_EL0 and CNTPCT_EL0 registers using the SET_ONE_REG |
| 6258 |
interface. No error will be returned, but the resulting offset will not be |
| 6259 |
applied. |
| 6260 |
|
| 6261 |
.. _KVM_ARM_GET_REG_WRITABLE_MASKS: |
| 6262 |
|
| 6263 |
4.139 KVM_ARM_GET_REG_WRITABLE_MASKS |
| 6264 |
------------------------------------ |
| 6265 |
|
| 6266 |
:Capability: KVM_CAP_ARM_SUPPORTED_REG_MASK_RANGES |
| 6267 |
:Architectures: arm64 |
| 6268 |
:Type: vm ioctl |
| 6269 |
:Parameters: struct reg_mask_range (in/out) |
| 6270 |
:Returns: 0 on success, < 0 on error |
| 6271 |
|
| 6272 |
|
| 6273 |
:: |
| 6274 |
|
| 6275 |
#define KVM_ARM_FEATURE_ID_RANGE 0 |
| 6276 |
#define KVM_ARM_FEATURE_ID_RANGE_SIZE (3 * 8 * 8) |
| 6277 |
|
| 6278 |
struct reg_mask_range { |
| 6279 |
__u64 addr; /* Pointer to mask array */ |
| 6280 |
__u32 range; /* Requested range */ |
| 6281 |
__u32 reserved[13]; |
| 6282 |
}; |
| 6283 |
|
| 6284 |
This ioctl copies the writable masks for a selected range of registers to |
| 6285 |
userspace. |
| 6286 |
|
| 6287 |
The ``addr`` field is a pointer to the destination array where KVM copies |
| 6288 |
the writable masks. |
| 6289 |
|
| 6290 |
The ``range`` field indicates the requested range of registers. |
| 6291 |
``KVM_CHECK_EXTENSION`` for the ``KVM_CAP_ARM_SUPPORTED_REG_MASK_RANGES`` |
| 6292 |
capability returns the supported ranges, expressed as a set of flags. Each |
| 6293 |
flag's bit index represents a possible value for the ``range`` field. |
| 6294 |
All other values are reserved for future use and KVM may return an error. |
| 6295 |
|
| 6296 |
The ``reserved[13]`` array is reserved for future use and should be 0, or |
| 6297 |
KVM may return an error. |
| 6298 |
|
| 6299 |
KVM_ARM_FEATURE_ID_RANGE (0) |
| 6300 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 6301 |
|
| 6302 |
The Feature ID range is defined as the AArch64 System register space with |
| 6303 |
op0==3, op1=={0, 1, 3}, CRn==0, CRm=={0-7}, op2=={0-7}. |
| 6304 |
|
| 6305 |
The mask returned array pointed to by ``addr`` is indexed by the macro |
| 6306 |
``ARM64_FEATURE_ID_RANGE_IDX(op0, op1, crn, crm, op2)``, allowing userspace |
| 6307 |
to know what fields can be changed for the system register described by |
| 6308 |
``op0, op1, crn, crm, op2``. KVM rejects ID register values that describe a |
| 6309 |
superset of the features supported by the system. |
| 6310 |
|
| 6311 |
4.140 KVM_SET_USER_MEMORY_REGION2 |
| 6312 |
--------------------------------- |
| 6313 |
|
| 6314 |
:Capability: KVM_CAP_USER_MEMORY2 |
| 6315 |
:Architectures: all |
| 6316 |
:Type: vm ioctl |
| 6317 |
:Parameters: struct kvm_userspace_memory_region2 (in) |
| 6318 |
:Returns: 0 on success, -1 on error |
| 6319 |
|
| 6320 |
KVM_SET_USER_MEMORY_REGION2 is an extension to KVM_SET_USER_MEMORY_REGION that |
| 6321 |
allows mapping guest_memfd memory into a guest. All fields shared with |
| 6322 |
KVM_SET_USER_MEMORY_REGION identically. Userspace can set KVM_MEM_GUEST_MEMFD |
| 6323 |
in flags to have KVM bind the memory region to a given guest_memfd range of |
| 6324 |
[guest_memfd_offset, guest_memfd_offset + memory_size]. The target guest_memfd |
| 6325 |
must point at a file created via KVM_CREATE_GUEST_MEMFD on the current VM, and |
| 6326 |
the target range must not be bound to any other memory region. All standard |
| 6327 |
bounds checks apply (use common sense). |
| 6328 |
|
| 6329 |
:: |
| 6330 |
|
| 6331 |
struct kvm_userspace_memory_region2 { |
| 6332 |
__u32 slot; |
| 6333 |
__u32 flags; |
| 6334 |
__u64 guest_phys_addr; |
| 6335 |
__u64 memory_size; /* bytes */ |
| 6336 |
__u64 userspace_addr; /* start of the userspace allocated memory */ |
| 6337 |
__u64 guest_memfd_offset; |
| 6338 |
__u32 guest_memfd; |
| 6339 |
__u32 pad1; |
| 6340 |
__u64 pad2[14]; |
| 6341 |
}; |
| 6342 |
|
| 6343 |
A KVM_MEM_GUEST_MEMFD region _must_ have a valid guest_memfd (private memory) and |
| 6344 |
userspace_addr (shared memory). However, "valid" for userspace_addr simply |
| 6345 |
means that the address itself must be a legal userspace address. The backing |
| 6346 |
mapping for userspace_addr is not required to be valid/populated at the time of |
| 6347 |
KVM_SET_USER_MEMORY_REGION2, e.g. shared memory can be lazily mapped/allocated |
| 6348 |
on-demand. |
| 6349 |
|
| 6350 |
When mapping a gfn into the guest, KVM selects shared vs. private, i.e consumes |
| 6351 |
userspace_addr vs. guest_memfd, based on the gfn's KVM_MEMORY_ATTRIBUTE_PRIVATE |
| 6352 |
state. At VM creation time, all memory is shared, i.e. the PRIVATE attribute |
| 6353 |
is '0' for all gfns. Userspace can control whether memory is shared/private by |
| 6354 |
toggling KVM_MEMORY_ATTRIBUTE_PRIVATE via KVM_SET_MEMORY_ATTRIBUTES as needed. |
| 6355 |
|
| 6356 |
S390: |
| 6357 |
^^^^^ |
| 6358 |
|
| 6359 |
Returns -EINVAL if the VM has the KVM_VM_S390_UCONTROL flag set. |
| 6360 |
Returns -EINVAL if called on a protected VM. |
| 6361 |
|
| 6362 |
4.141 KVM_SET_MEMORY_ATTRIBUTES |
| 6363 |
------------------------------- |
| 6364 |
|
| 6365 |
:Capability: KVM_CAP_MEMORY_ATTRIBUTES |
| 6366 |
:Architectures: x86 |
| 6367 |
:Type: vm ioctl |
| 6368 |
:Parameters: struct kvm_memory_attributes (in) |
| 6369 |
:Returns: 0 on success, <0 on error |
| 6370 |
|
| 6371 |
KVM_SET_MEMORY_ATTRIBUTES allows userspace to set memory attributes for a range |
| 6372 |
of guest physical memory. |
| 6373 |
|
| 6374 |
:: |
| 6375 |
|
| 6376 |
struct kvm_memory_attributes { |
| 6377 |
__u64 address; |
| 6378 |
__u64 size; |
| 6379 |
__u64 attributes; |
| 6380 |
__u64 flags; |
| 6381 |
}; |
| 6382 |
|
| 6383 |
#define KVM_MEMORY_ATTRIBUTE_PRIVATE (1ULL << 3) |
| 6384 |
|
| 6385 |
The address and size must be page aligned. The supported attributes can be |
| 6386 |
retrieved via ioctl(KVM_CHECK_EXTENSION) on KVM_CAP_MEMORY_ATTRIBUTES. If |
| 6387 |
executed on a VM, KVM_CAP_MEMORY_ATTRIBUTES precisely returns the attributes |
| 6388 |
supported by that VM. If executed at system scope, KVM_CAP_MEMORY_ATTRIBUTES |
| 6389 |
returns all attributes supported by KVM. The only attribute defined at this |
| 6390 |
time is KVM_MEMORY_ATTRIBUTE_PRIVATE, which marks the associated gfn as being |
| 6391 |
guest private memory. |
| 6392 |
|
| 6393 |
Note, there is no "get" API. Userspace is responsible for explicitly tracking |
| 6394 |
the state of a gfn/page as needed. |
| 6395 |
|
| 6396 |
The "flags" field is reserved for future extensions and must be '0'. |
| 6397 |
|
| 6398 |
4.142 KVM_CREATE_GUEST_MEMFD |
| 6399 |
---------------------------- |
| 6400 |
|
| 6401 |
:Capability: KVM_CAP_GUEST_MEMFD |
| 6402 |
:Architectures: none |
| 6403 |
:Type: vm ioctl |
| 6404 |
:Parameters: struct kvm_create_guest_memfd(in) |
| 6405 |
:Returns: A file descriptor on success, <0 on error |
| 6406 |
|
| 6407 |
KVM_CREATE_GUEST_MEMFD creates an anonymous file and returns a file descriptor |
| 6408 |
that refers to it. guest_memfd files are roughly analogous to files created |
| 6409 |
via memfd_create(), e.g. guest_memfd files live in RAM, have volatile storage, |
| 6410 |
and are automatically released when the last reference is dropped. Unlike |
| 6411 |
"regular" memfd_create() files, guest_memfd files are bound to their owning |
| 6412 |
virtual machine (see below), cannot be mapped, read, or written by userspace, |
| 6413 |
and cannot be resized (guest_memfd files do however support PUNCH_HOLE). |
| 6414 |
|
| 6415 |
:: |
| 6416 |
|
| 6417 |
struct kvm_create_guest_memfd { |
| 6418 |
__u64 size; |
| 6419 |
__u64 flags; |
| 6420 |
__u64 reserved[6]; |
| 6421 |
}; |
| 6422 |
|
| 6423 |
Conceptually, the inode backing a guest_memfd file represents physical memory, |
| 6424 |
i.e. is coupled to the virtual machine as a thing, not to a "struct kvm". The |
| 6425 |
file itself, which is bound to a "struct kvm", is that instance's view of the |
| 6426 |
underlying memory, e.g. effectively provides the translation of guest addresses |
| 6427 |
to host memory. This allows for use cases where multiple KVM structures are |
| 6428 |
used to manage a single virtual machine, e.g. when performing intrahost |
| 6429 |
migration of a virtual machine. |
| 6430 |
|
| 6431 |
KVM currently only supports mapping guest_memfd via KVM_SET_USER_MEMORY_REGION2, |
| 6432 |
and more specifically via the guest_memfd and guest_memfd_offset fields in |
| 6433 |
"struct kvm_userspace_memory_region2", where guest_memfd_offset is the offset |
| 6434 |
into the guest_memfd instance. For a given guest_memfd file, there can be at |
| 6435 |
most one mapping per page, i.e. binding multiple memory regions to a single |
| 6436 |
guest_memfd range is not allowed (any number of memory regions can be bound to |
| 6437 |
a single guest_memfd file, but the bound ranges must not overlap). |
| 6438 |
|
| 6439 |
The capability KVM_CAP_GUEST_MEMFD_FLAGS enumerates the `flags` that can be |
| 6440 |
specified via KVM_CREATE_GUEST_MEMFD. Currently defined flags: |
| 6441 |
|
| 6442 |
============================ ================================================ |
| 6443 |
GUEST_MEMFD_FLAG_MMAP Enable using mmap() on the guest_memfd file |
| 6444 |
descriptor. |
| 6445 |
GUEST_MEMFD_FLAG_INIT_SHARED Make all memory in the file shared during |
| 6446 |
KVM_CREATE_GUEST_MEMFD (memory files created |
| 6447 |
without INIT_SHARED will be marked private). |
| 6448 |
Shared memory can be faulted into host userspace |
| 6449 |
page tables. Private memory cannot. |
| 6450 |
============================ ================================================ |
| 6451 |
|
| 6452 |
When the KVM MMU performs a PFN lookup to service a guest fault and the backing |
| 6453 |
guest_memfd has the GUEST_MEMFD_FLAG_MMAP set, then the fault will always be |
| 6454 |
consumed from guest_memfd, regardless of whether it is a shared or a private |
| 6455 |
fault. |
| 6456 |
|
| 6457 |
See KVM_SET_USER_MEMORY_REGION2 for additional details. |
| 6458 |
|
| 6459 |
4.143 KVM_PRE_FAULT_MEMORY |
| 6460 |
--------------------------- |
| 6461 |
|
| 6462 |
:Capability: KVM_CAP_PRE_FAULT_MEMORY |
| 6463 |
:Architectures: none |
| 6464 |
:Type: vcpu ioctl |
| 6465 |
:Parameters: struct kvm_pre_fault_memory (in/out) |
| 6466 |
:Returns: 0 if at least one page is processed, < 0 on error |
| 6467 |
|
| 6468 |
Errors: |
| 6469 |
|
| 6470 |
========== =============================================================== |
| 6471 |
EINVAL The specified `gpa` and `size` were invalid (e.g. not |
| 6472 |
page aligned, causes an overflow, or size is zero). |
| 6473 |
ENOENT The specified `gpa` is outside defined memslots. |
| 6474 |
EINTR An unmasked signal is pending and no page was processed. |
| 6475 |
EFAULT The parameter address was invalid. |
| 6476 |
EOPNOTSUPP Mapping memory for a GPA is unsupported by the |
| 6477 |
hypervisor, and/or for the current vCPU state/mode. |
| 6478 |
EIO unexpected error conditions (also causes a WARN) |
| 6479 |
========== =============================================================== |
| 6480 |
|
| 6481 |
:: |
| 6482 |
|
| 6483 |
struct kvm_pre_fault_memory { |
| 6484 |
/* in/out */ |
| 6485 |
__u64 gpa; |
| 6486 |
__u64 size; |
| 6487 |
/* in */ |
| 6488 |
__u64 flags; |
| 6489 |
__u64 padding[5]; |
| 6490 |
}; |
| 6491 |
|
| 6492 |
KVM_PRE_FAULT_MEMORY populates KVM's stage-2 page tables used to map memory |
| 6493 |
for the current vCPU state. KVM maps memory as if the vCPU generated a |
| 6494 |
stage-2 read page fault, e.g. faults in memory as needed, but doesn't break |
| 6495 |
CoW. However, KVM does not mark any newly created stage-2 PTE as Accessed. |
| 6496 |
|
| 6497 |
In the case of confidential VM types where there is an initial set up of |
| 6498 |
private guest memory before the guest is 'finalized'/measured, this ioctl |
| 6499 |
should only be issued after completing all the necessary setup to put the |
| 6500 |
guest into a 'finalized' state so that the above semantics can be reliably |
| 6501 |
ensured. |
| 6502 |
|
| 6503 |
In some cases, multiple vCPUs might share the page tables. In this |
| 6504 |
case, the ioctl can be called in parallel. |
| 6505 |
|
| 6506 |
When the ioctl returns, the input values are updated to point to the |
| 6507 |
remaining range. If `size` > 0 on return, the caller can just issue |
| 6508 |
the ioctl again with the same `struct kvm_map_memory` argument. |
| 6509 |
|
| 6510 |
Shadow page tables cannot support this ioctl because they |
| 6511 |
are indexed by virtual address or nested guest physical address. |
| 6512 |
Calling this ioctl when the guest is using shadow page tables (for |
| 6513 |
example because it is running a nested guest with nested page tables) |
| 6514 |
will fail with `EOPNOTSUPP` even if `KVM_CHECK_EXTENSION` reports |
| 6515 |
the capability to be present. |
| 6516 |
|
| 6517 |
`flags` must currently be zero. |
| 6518 |
|
| 6519 |
4.144 KVM_S390_KEYOP |
| 6520 |
-------------------- |
| 6521 |
|
| 6522 |
:Capability: KVM_CAP_S390_KEYOP |
| 6523 |
:Architectures: s390 |
| 6524 |
:Type: vm ioctl |
| 6525 |
:Parameters: struct kvm_s390_keyop (in/out) |
| 6526 |
:Returns: 0 in case of success, < 0 on error |
| 6527 |
|
| 6528 |
The specified key operation is performed on the given guest address. The |
| 6529 |
previous storage key (or the relevant part thereof) will be returned in |
| 6530 |
`key`. |
| 6531 |
|
| 6532 |
:: |
| 6533 |
|
| 6534 |
struct kvm_s390_keyop { |
| 6535 |
__u64 guest_addr; |
| 6536 |
__u8 key; |
| 6537 |
__u8 operation; |
| 6538 |
}; |
| 6539 |
|
| 6540 |
Currently supported values for ``operation``: |
| 6541 |
|
| 6542 |
KVM_S390_KEYOP_ISKE |
| 6543 |
Returns the storage key for the guest address ``guest_addr`` in ``key``. |
| 6544 |
|
| 6545 |
KVM_S390_KEYOP_RRBE |
| 6546 |
Resets the reference bit for the guest address ``guest_addr``, returning the |
| 6547 |
R and C bits of the old storage key in ``key``; the remaining fields of |
| 6548 |
the storage key will be set to 0. |
| 6549 |
|
| 6550 |
KVM_S390_KEYOP_SSKE |
| 6551 |
Sets the storage key for the guest address ``guest_addr`` to the key |
| 6552 |
specified in ``key``, returning the previous value in ``key``. |
| 6553 |
|
| 6554 |
.. _kvm_run: |
| 6555 |
|
| 6556 |
5. The kvm_run structure |
| 6557 |
======================== |
| 6558 |
|
| 6559 |
Application code obtains a pointer to the kvm_run structure by |
| 6560 |
mmap()ing a vcpu fd. From that point, application code can control |
| 6561 |
execution by changing fields in kvm_run prior to calling the KVM_RUN |
| 6562 |
ioctl, and obtain information about the reason KVM_RUN returned by |
| 6563 |
looking up structure members. |
| 6564 |
|
| 6565 |
:: |
| 6566 |
|
| 6567 |
struct kvm_run { |
| 6568 |
/* in */ |
| 6569 |
__u8 request_interrupt_window; |
| 6570 |
|
| 6571 |
Request that KVM_RUN return when it becomes possible to inject external |
| 6572 |
interrupts into the guest. Useful in conjunction with KVM_INTERRUPT. |
| 6573 |
|
| 6574 |
:: |
| 6575 |
|
| 6576 |
__u8 immediate_exit; |
| 6577 |
|
| 6578 |
This field is polled once when KVM_RUN starts; if non-zero, KVM_RUN |
| 6579 |
exits immediately, returning -EINTR. In the common scenario where a |
| 6580 |
signal is used to "kick" a VCPU out of KVM_RUN, this field can be used |
| 6581 |
to avoid usage of KVM_SET_SIGNAL_MASK, which has worse scalability. |
| 6582 |
Rather than blocking the signal outside KVM_RUN, userspace can set up |
| 6583 |
a signal handler that sets run->immediate_exit to a non-zero value. |
| 6584 |
|
| 6585 |
This field is ignored if KVM_CAP_IMMEDIATE_EXIT is not available. |
| 6586 |
|
| 6587 |
:: |
| 6588 |
|
| 6589 |
__u8 padding1[6]; |
| 6590 |
|
| 6591 |
/* out */ |
| 6592 |
__u32 exit_reason; |
| 6593 |
|
| 6594 |
When KVM_RUN has returned successfully (return value 0), this informs |
| 6595 |
application code why KVM_RUN has returned. Allowable values for this |
| 6596 |
field are detailed below. |
| 6597 |
|
| 6598 |
:: |
| 6599 |
|
| 6600 |
__u8 ready_for_interrupt_injection; |
| 6601 |
|
| 6602 |
If request_interrupt_window has been specified, this field indicates |
| 6603 |
an interrupt can be injected now with KVM_INTERRUPT. |
| 6604 |
|
| 6605 |
:: |
| 6606 |
|
| 6607 |
__u8 if_flag; |
| 6608 |
|
| 6609 |
The value of the current interrupt flag. Only valid if in-kernel |
| 6610 |
local APIC is not used. |
| 6611 |
|
| 6612 |
:: |
| 6613 |
|
| 6614 |
__u16 flags; |
| 6615 |
|
| 6616 |
More architecture-specific flags detailing state of the VCPU that may |
| 6617 |
affect the device's behavior. Current defined flags:: |
| 6618 |
|
| 6619 |
/* x86, set if the VCPU is in system management mode */ |
| 6620 |
#define KVM_RUN_X86_SMM (1 << 0) |
| 6621 |
/* x86, set if bus lock detected in VM */ |
| 6622 |
#define KVM_RUN_X86_BUS_LOCK (1 << 1) |
| 6623 |
/* x86, set if the VCPU is executing a nested (L2) guest */ |
| 6624 |
#define KVM_RUN_X86_GUEST_MODE (1 << 2) |
| 6625 |
|
| 6626 |
/* arm64, set for KVM_EXIT_DEBUG */ |
| 6627 |
#define KVM_DEBUG_ARCH_HSR_HIGH_VALID (1 << 0) |
| 6628 |
|
| 6629 |
:: |
| 6630 |
|
| 6631 |
/* in (pre_kvm_run), out (post_kvm_run) */ |
| 6632 |
__u64 cr8; |
| 6633 |
|
| 6634 |
The value of the cr8 register. Only valid if in-kernel local APIC is |
| 6635 |
not used. Both input and output. |
| 6636 |
|
| 6637 |
:: |
| 6638 |
|
| 6639 |
__u64 apic_base; |
| 6640 |
|
| 6641 |
The value of the APIC BASE msr. Only valid if in-kernel local |
| 6642 |
APIC is not used. Both input and output. |
| 6643 |
|
| 6644 |
:: |
| 6645 |
|
| 6646 |
union { |
| 6647 |
/* KVM_EXIT_UNKNOWN */ |
| 6648 |
struct { |
| 6649 |
__u64 hardware_exit_reason; |
| 6650 |
} hw; |
| 6651 |
|
| 6652 |
If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown |
| 6653 |
reasons. Further architecture-specific information is available in |
| 6654 |
hardware_exit_reason. |
| 6655 |
|
| 6656 |
:: |
| 6657 |
|
| 6658 |
/* KVM_EXIT_FAIL_ENTRY */ |
| 6659 |
struct { |
| 6660 |
__u64 hardware_entry_failure_reason; |
| 6661 |
__u32 cpu; /* if KVM_LAST_CPU */ |
| 6662 |
} fail_entry; |
| 6663 |
|
| 6664 |
If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due |
| 6665 |
to unknown reasons. Further architecture-specific information is |
| 6666 |
available in hardware_entry_failure_reason. |
| 6667 |
|
| 6668 |
:: |
| 6669 |
|
| 6670 |
/* KVM_EXIT_EXCEPTION */ |
| 6671 |
struct { |
| 6672 |
__u32 exception; |
| 6673 |
__u32 error_code; |
| 6674 |
} ex; |
| 6675 |
|
| 6676 |
Unused. |
| 6677 |
|
| 6678 |
:: |
| 6679 |
|
| 6680 |
/* KVM_EXIT_IO */ |
| 6681 |
struct { |
| 6682 |
#define KVM_EXIT_IO_IN 0 |
| 6683 |
#define KVM_EXIT_IO_OUT 1 |
| 6684 |
__u8 direction; |
| 6685 |
__u8 size; /* bytes */ |
| 6686 |
__u16 port; |
| 6687 |
__u32 count; |
| 6688 |
__u64 data_offset; /* relative to kvm_run start */ |
| 6689 |
} io; |
| 6690 |
|
| 6691 |
If exit_reason is KVM_EXIT_IO, then the vcpu has |
| 6692 |
executed a port I/O instruction which could not be satisfied by kvm. |
| 6693 |
data_offset describes where the data is located (KVM_EXIT_IO_OUT) or |
| 6694 |
where kvm expects application code to place the data for the next |
| 6695 |
KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a packed array. |
| 6696 |
|
| 6697 |
:: |
| 6698 |
|
| 6699 |
/* KVM_EXIT_DEBUG */ |
| 6700 |
struct { |
| 6701 |
struct kvm_debug_exit_arch arch; |
| 6702 |
} debug; |
| 6703 |
|
| 6704 |
If the exit_reason is KVM_EXIT_DEBUG, then a vcpu is processing a debug event |
| 6705 |
for which architecture specific information is returned. |
| 6706 |
|
| 6707 |
:: |
| 6708 |
|
| 6709 |
/* KVM_EXIT_MMIO */ |
| 6710 |
struct { |
| 6711 |
__u64 phys_addr; |
| 6712 |
__u8 data[8]; |
| 6713 |
__u32 len; |
| 6714 |
__u8 is_write; |
| 6715 |
} mmio; |
| 6716 |
|
| 6717 |
If exit_reason is KVM_EXIT_MMIO, then the vcpu has |
| 6718 |
executed a memory-mapped I/O instruction which could not be satisfied |
| 6719 |
by kvm. The 'data' member contains the written data if 'is_write' is |
| 6720 |
true, and should be filled by application code otherwise. |
| 6721 |
|
| 6722 |
The 'data' member contains, in its first 'len' bytes, the value as it would |
| 6723 |
appear if the VCPU performed a load or store of the appropriate width directly |
| 6724 |
to the byte array. |
| 6725 |
|
| 6726 |
.. note:: |
| 6727 |
|
| 6728 |
For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR, KVM_EXIT_XEN, |
| 6729 |
KVM_EXIT_EPR, KVM_EXIT_HYPERCALL, KVM_EXIT_TDX, |
| 6730 |
KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR the corresponding |
| 6731 |
operations are complete (and guest state is consistent) only after userspace |
| 6732 |
has re-entered the kernel with KVM_RUN. The kernel side will first finish |
| 6733 |
incomplete operations and then check for pending signals. |
| 6734 |
|
| 6735 |
The pending state of the operation is not preserved in state which is |
| 6736 |
visible to userspace, thus userspace should ensure that the operation is |
| 6737 |
completed before performing a live migration. Userspace can re-enter the |
| 6738 |
guest with an unmasked signal pending or with the immediate_exit field set |
| 6739 |
to complete pending operations without allowing any further instructions |
| 6740 |
to be executed. |
| 6741 |
|
| 6742 |
:: |
| 6743 |
|
| 6744 |
/* KVM_EXIT_HYPERCALL */ |
| 6745 |
struct { |
| 6746 |
__u64 nr; |
| 6747 |
__u64 args[6]; |
| 6748 |
__u64 ret; |
| 6749 |
__u64 flags; |
| 6750 |
} hypercall; |
| 6751 |
|
| 6752 |
|
| 6753 |
It is strongly recommended that userspace use ``KVM_EXIT_IO`` (x86) or |
| 6754 |
``KVM_EXIT_MMIO`` (all except s390) to implement functionality that |
| 6755 |
requires a guest to interact with host userspace. |
| 6756 |
|
| 6757 |
.. note:: KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO. |
| 6758 |
|
| 6759 |
For arm64: |
| 6760 |
---------- |
| 6761 |
|
| 6762 |
SMCCC exits can be enabled depending on the configuration of the SMCCC |
| 6763 |
filter. See the Documentation/virt/kvm/devices/vm.rst |
| 6764 |
``KVM_ARM_SMCCC_FILTER`` for more details. |
| 6765 |
|
| 6766 |
``nr`` contains the function ID of the guest's SMCCC call. Userspace is |
| 6767 |
expected to use the ``KVM_GET_ONE_REG`` ioctl to retrieve the call |
| 6768 |
parameters from the vCPU's GPRs. |
| 6769 |
|
| 6770 |
Definition of ``flags``: |
| 6771 |
- ``KVM_HYPERCALL_EXIT_SMC``: Indicates that the guest used the SMC |
| 6772 |
conduit to initiate the SMCCC call. If this bit is 0 then the guest |
| 6773 |
used the HVC conduit for the SMCCC call. |
| 6774 |
|
| 6775 |
- ``KVM_HYPERCALL_EXIT_16BIT``: Indicates that the guest used a 16bit |
| 6776 |
instruction to initiate the SMCCC call. If this bit is 0 then the |
| 6777 |
guest used a 32bit instruction. An AArch64 guest always has this |
| 6778 |
bit set to 0. |
| 6779 |
|
| 6780 |
At the point of exit, PC points to the instruction immediately following |
| 6781 |
the trapping instruction. |
| 6782 |
|
| 6783 |
:: |
| 6784 |
|
| 6785 |
/* KVM_EXIT_TPR_ACCESS */ |
| 6786 |
struct { |
| 6787 |
__u64 rip; |
| 6788 |
__u32 is_write; |
| 6789 |
__u32 pad; |
| 6790 |
} tpr_access; |
| 6791 |
|
| 6792 |
To be documented (KVM_TPR_ACCESS_REPORTING). |
| 6793 |
|
| 6794 |
:: |
| 6795 |
|
| 6796 |
/* KVM_EXIT_S390_SIEIC */ |
| 6797 |
struct { |
| 6798 |
__u8 icptcode; |
| 6799 |
__u64 mask; /* psw upper half */ |
| 6800 |
__u64 addr; /* psw lower half */ |
| 6801 |
__u16 ipa; |
| 6802 |
__u32 ipb; |
| 6803 |
} s390_sieic; |
| 6804 |
|
| 6805 |
s390 specific. |
| 6806 |
|
| 6807 |
:: |
| 6808 |
|
| 6809 |
/* KVM_EXIT_S390_RESET */ |
| 6810 |
#define KVM_S390_RESET_POR 1 |
| 6811 |
#define KVM_S390_RESET_CLEAR 2 |
| 6812 |
#define KVM_S390_RESET_SUBSYSTEM 4 |
| 6813 |
#define KVM_S390_RESET_CPU_INIT 8 |
| 6814 |
#define KVM_S390_RESET_IPL 16 |
| 6815 |
__u64 s390_reset_flags; |
| 6816 |
|
| 6817 |
s390 specific. |
| 6818 |
|
| 6819 |
:: |
| 6820 |
|
| 6821 |
/* KVM_EXIT_S390_UCONTROL */ |
| 6822 |
struct { |
| 6823 |
__u64 trans_exc_code; |
| 6824 |
__u32 pgm_code; |
| 6825 |
} s390_ucontrol; |
| 6826 |
|
| 6827 |
s390 specific. A page fault has occurred for a user controlled virtual |
| 6828 |
machine (KVM_VM_S390_UNCONTROL) on its host page table that cannot be |
| 6829 |
resolved by the kernel. |
| 6830 |
The program code and the translation exception code that were placed |
| 6831 |
in the cpu's lowcore are presented here as defined by the z Architecture |
| 6832 |
Principles of Operation Book in the Chapter for Dynamic Address Translation |
| 6833 |
(DAT) |
| 6834 |
|
| 6835 |
:: |
| 6836 |
|
| 6837 |
/* KVM_EXIT_DCR */ |
| 6838 |
struct { |
| 6839 |
__u32 dcrn; |
| 6840 |
__u32 data; |
| 6841 |
__u8 is_write; |
| 6842 |
} dcr; |
| 6843 |
|
| 6844 |
Deprecated - was used for 440 KVM. |
| 6845 |
|
| 6846 |
:: |
| 6847 |
|
| 6848 |
/* KVM_EXIT_OSI */ |
| 6849 |
struct { |
| 6850 |
__u64 gprs[32]; |
| 6851 |
} osi; |
| 6852 |
|
| 6853 |
MOL uses a special hypercall interface it calls 'OSI'. To enable it, we catch |
| 6854 |
hypercalls and exit with this exit struct that contains all the guest gprs. |
| 6855 |
|
| 6856 |
If exit_reason is KVM_EXIT_OSI, then the vcpu has triggered such a hypercall. |
| 6857 |
Userspace can now handle the hypercall and when it's done modify the gprs as |
| 6858 |
necessary. Upon guest entry all guest GPRs will then be replaced by the values |
| 6859 |
in this struct. |
| 6860 |
|
| 6861 |
:: |
| 6862 |
|
| 6863 |
/* KVM_EXIT_PAPR_HCALL */ |
| 6864 |
struct { |
| 6865 |
__u64 nr; |
| 6866 |
__u64 ret; |
| 6867 |
__u64 args[9]; |
| 6868 |
} papr_hcall; |
| 6869 |
|
| 6870 |
This is used on 64-bit PowerPC when emulating a pSeries partition, |
| 6871 |
e.g. with the 'pseries' machine type in qemu. It occurs when the |
| 6872 |
guest does a hypercall using the 'sc 1' instruction. The 'nr' field |
| 6873 |
contains the hypercall number (from the guest R3), and 'args' contains |
| 6874 |
the arguments (from the guest R4 - R12). Userspace should put the |
| 6875 |
return code in 'ret' and any extra returned values in args[]. |
| 6876 |
The possible hypercalls are defined in the Power Architecture Platform |
| 6877 |
Requirements (PAPR) document available from www.power.org (free |
| 6878 |
developer registration required to access it). |
| 6879 |
|
| 6880 |
:: |
| 6881 |
|
| 6882 |
/* KVM_EXIT_S390_TSCH */ |
| 6883 |
struct { |
| 6884 |
__u16 subchannel_id; |
| 6885 |
__u16 subchannel_nr; |
| 6886 |
__u32 io_int_parm; |
| 6887 |
__u32 io_int_word; |
| 6888 |
__u32 ipb; |
| 6889 |
__u8 dequeued; |
| 6890 |
} s390_tsch; |
| 6891 |
|
| 6892 |
s390 specific. This exit occurs when KVM_CAP_S390_CSS_SUPPORT has been enabled |
| 6893 |
and TEST SUBCHANNEL was intercepted. If dequeued is set, a pending I/O |
| 6894 |
interrupt for the target subchannel has been dequeued and subchannel_id, |
| 6895 |
subchannel_nr, io_int_parm and io_int_word contain the parameters for that |
| 6896 |
interrupt. ipb is needed for instruction parameter decoding. |
| 6897 |
|
| 6898 |
:: |
| 6899 |
|
| 6900 |
/* KVM_EXIT_EPR */ |
| 6901 |
struct { |
| 6902 |
__u32 epr; |
| 6903 |
} epr; |
| 6904 |
|
| 6905 |
On FSL BookE PowerPC chips, the interrupt controller has a fast patch |
| 6906 |
interrupt acknowledge path to the core. When the core successfully |
| 6907 |
delivers an interrupt, it automatically populates the EPR register with |
| 6908 |
the interrupt vector number and acknowledges the interrupt inside |
| 6909 |
the interrupt controller. |
| 6910 |
|
| 6911 |
In case the interrupt controller lives in user space, we need to do |
| 6912 |
the interrupt acknowledge cycle through it to fetch the next to be |
| 6913 |
delivered interrupt vector using this exit. |
| 6914 |
|
| 6915 |
It gets triggered whenever both KVM_CAP_PPC_EPR are enabled and an |
| 6916 |
external interrupt has just been delivered into the guest. User space |
| 6917 |
should put the acknowledged interrupt vector into the 'epr' field. |
| 6918 |
|
| 6919 |
:: |
| 6920 |
|
| 6921 |
/* KVM_EXIT_SYSTEM_EVENT */ |
| 6922 |
struct { |
| 6923 |
#define KVM_SYSTEM_EVENT_SHUTDOWN 1 |
| 6924 |
#define KVM_SYSTEM_EVENT_RESET 2 |
| 6925 |
#define KVM_SYSTEM_EVENT_CRASH 3 |
| 6926 |
#define KVM_SYSTEM_EVENT_WAKEUP 4 |
| 6927 |
#define KVM_SYSTEM_EVENT_SUSPEND 5 |
| 6928 |
#define KVM_SYSTEM_EVENT_SEV_TERM 6 |
| 6929 |
#define KVM_SYSTEM_EVENT_TDX_FATAL 7 |
| 6930 |
__u32 type; |
| 6931 |
__u32 ndata; |
| 6932 |
__u64 data[16]; |
| 6933 |
} system_event; |
| 6934 |
|
| 6935 |
If exit_reason is KVM_EXIT_SYSTEM_EVENT then the vcpu has triggered |
| 6936 |
a system-level event using some architecture specific mechanism (hypercall |
| 6937 |
or some special instruction). In case of ARM64, this is triggered using |
| 6938 |
HVC instruction based PSCI call from the vcpu. |
| 6939 |
|
| 6940 |
The 'type' field describes the system-level event type. |
| 6941 |
Valid values for 'type' are: |
| 6942 |
|
| 6943 |
- KVM_SYSTEM_EVENT_SHUTDOWN -- the guest has requested a shutdown of the |
| 6944 |
VM. Userspace is not obliged to honour this, and if it does honour |
| 6945 |
this does not need to destroy the VM synchronously (ie it may call |
| 6946 |
KVM_RUN again before shutdown finally occurs). |
| 6947 |
- KVM_SYSTEM_EVENT_RESET -- the guest has requested a reset of the VM. |
| 6948 |
As with SHUTDOWN, userspace can choose to ignore the request, or |
| 6949 |
to schedule the reset to occur in the future and may call KVM_RUN again. |
| 6950 |
- KVM_SYSTEM_EVENT_CRASH -- the guest crash occurred and the guest |
| 6951 |
has requested a crash condition maintenance. Userspace can choose |
| 6952 |
to ignore the request, or to gather VM memory core dump and/or |
| 6953 |
reset/shutdown of the VM. |
| 6954 |
- KVM_SYSTEM_EVENT_SEV_TERM -- an AMD SEV guest requested termination. |
| 6955 |
The guest physical address of the guest's GHCB is stored in `data[0]`. |
| 6956 |
- KVM_SYSTEM_EVENT_TDX_FATAL -- a TDX guest reported a fatal error state. |
| 6957 |
KVM doesn't do any parsing or conversion, it just dumps 16 general-purpose |
| 6958 |
registers to userspace, in ascending order of the 4-bit indices for x86-64 |
| 6959 |
general-purpose registers in instruction encoding, as defined in the Intel |
| 6960 |
SDM. |
| 6961 |
- KVM_SYSTEM_EVENT_WAKEUP -- the exiting vCPU is in a suspended state and |
| 6962 |
KVM has recognized a wakeup event. Userspace may honor this event by |
| 6963 |
marking the exiting vCPU as runnable, or deny it and call KVM_RUN again. |
| 6964 |
- KVM_SYSTEM_EVENT_SUSPEND -- the guest has requested a suspension of |
| 6965 |
the VM. |
| 6966 |
|
| 6967 |
If KVM_CAP_SYSTEM_EVENT_DATA is present, the 'data' field can contain |
| 6968 |
architecture specific information for the system-level event. Only |
| 6969 |
the first `ndata` items (possibly zero) of the data array are valid. |
| 6970 |
|
| 6971 |
- for arm64, data[0] is set to KVM_SYSTEM_EVENT_RESET_FLAG_PSCI_RESET2 if |
| 6972 |
the guest issued a SYSTEM_RESET2 call according to v1.1 of the PSCI |
| 6973 |
specification. |
| 6974 |
|
| 6975 |
- for arm64, data[0] is set to KVM_SYSTEM_EVENT_SHUTDOWN_FLAG_PSCI_OFF2 |
| 6976 |
if the guest issued a SYSTEM_OFF2 call according to v1.3 of the PSCI |
| 6977 |
specification. |
| 6978 |
|
| 6979 |
- for RISC-V, data[0] is set to the value of the second argument of the |
| 6980 |
``sbi_system_reset`` call. |
| 6981 |
|
| 6982 |
Previous versions of Linux defined a `flags` member in this struct. The |
| 6983 |
field is now aliased to `data[0]`. Userspace can assume that it is only |
| 6984 |
written if ndata is greater than 0. |
| 6985 |
|
| 6986 |
For arm/arm64: |
| 6987 |
-------------- |
| 6988 |
|
| 6989 |
KVM_SYSTEM_EVENT_SUSPEND exits are enabled with the |
| 6990 |
KVM_CAP_ARM_SYSTEM_SUSPEND VM capability. If a guest invokes the PSCI |
| 6991 |
SYSTEM_SUSPEND function, KVM will exit to userspace with this event |
| 6992 |
type. |
| 6993 |
|
| 6994 |
It is the sole responsibility of userspace to implement the PSCI |
| 6995 |
SYSTEM_SUSPEND call according to ARM DEN0022D.b 5.19 "SYSTEM_SUSPEND". |
| 6996 |
KVM does not change the vCPU's state before exiting to userspace, so |
| 6997 |
the call parameters are left in-place in the vCPU registers. |
| 6998 |
|
| 6999 |
Userspace is _required_ to take action for such an exit. It must |
| 7000 |
either: |
| 7001 |
|
| 7002 |
- Honor the guest request to suspend the VM. Userspace can request |
| 7003 |
in-kernel emulation of suspension by setting the calling vCPU's |
| 7004 |
state to KVM_MP_STATE_SUSPENDED. Userspace must configure the vCPU's |
| 7005 |
state according to the parameters passed to the PSCI function when |
| 7006 |
the calling vCPU is resumed. See ARM DEN0022D.b 5.19.1 "Intended use" |
| 7007 |
for details on the function parameters. |
| 7008 |
|
| 7009 |
- Deny the guest request to suspend the VM. See ARM DEN0022D.b 5.19.2 |
| 7010 |
"Caller responsibilities" for possible return values. |
| 7011 |
|
| 7012 |
Hibernation using the PSCI SYSTEM_OFF2 call is enabled when PSCI v1.3 |
| 7013 |
is enabled. If a guest invokes the PSCI SYSTEM_OFF2 function, KVM will |
| 7014 |
exit to userspace with the KVM_SYSTEM_EVENT_SHUTDOWN event type and with |
| 7015 |
data[0] set to KVM_SYSTEM_EVENT_SHUTDOWN_FLAG_PSCI_OFF2. The only |
| 7016 |
supported hibernate type for the SYSTEM_OFF2 function is HIBERNATE_OFF. |
| 7017 |
|
| 7018 |
:: |
| 7019 |
|
| 7020 |
/* KVM_EXIT_IOAPIC_EOI */ |
| 7021 |
struct { |
| 7022 |
__u8 vector; |
| 7023 |
} eoi; |
| 7024 |
|
| 7025 |
Indicates that the VCPU's in-kernel local APIC received an EOI for a |
| 7026 |
level-triggered IOAPIC interrupt. This exit only triggers when the |
| 7027 |
IOAPIC is implemented in userspace (i.e. KVM_CAP_SPLIT_IRQCHIP is enabled); |
| 7028 |
the userspace IOAPIC should process the EOI and retrigger the interrupt if |
| 7029 |
it is still asserted. Vector is the LAPIC interrupt vector for which the |
| 7030 |
EOI was received. |
| 7031 |
|
| 7032 |
:: |
| 7033 |
|
| 7034 |
struct kvm_hyperv_exit { |
| 7035 |
#define KVM_EXIT_HYPERV_SYNIC 1 |
| 7036 |
#define KVM_EXIT_HYPERV_HCALL 2 |
| 7037 |
#define KVM_EXIT_HYPERV_SYNDBG 3 |
| 7038 |
__u32 type; |
| 7039 |
__u32 pad1; |
| 7040 |
union { |
| 7041 |
struct { |
| 7042 |
__u32 msr; |
| 7043 |
__u32 pad2; |
| 7044 |
__u64 control; |
| 7045 |
__u64 evt_page; |
| 7046 |
__u64 msg_page; |
| 7047 |
} synic; |
| 7048 |
struct { |
| 7049 |
__u64 input; |
| 7050 |
__u64 result; |
| 7051 |
__u64 params[2]; |
| 7052 |
} hcall; |
| 7053 |
struct { |
| 7054 |
__u32 msr; |
| 7055 |
__u32 pad2; |
| 7056 |
__u64 control; |
| 7057 |
__u64 status; |
| 7058 |
__u64 send_page; |
| 7059 |
__u64 recv_page; |
| 7060 |
__u64 pending_page; |
| 7061 |
} syndbg; |
| 7062 |
} u; |
| 7063 |
}; |
| 7064 |
/* KVM_EXIT_HYPERV */ |
| 7065 |
struct kvm_hyperv_exit hyperv; |
| 7066 |
|
| 7067 |
Indicates that the VCPU exits into userspace to process some tasks |
| 7068 |
related to Hyper-V emulation. |
| 7069 |
|
| 7070 |
Valid values for 'type' are: |
| 7071 |
|
| 7072 |
- KVM_EXIT_HYPERV_SYNIC -- synchronously notify user-space about |
| 7073 |
|
| 7074 |
Hyper-V SynIC state change. Notification is used to remap SynIC |
| 7075 |
event/message pages and to enable/disable SynIC messages/events processing |
| 7076 |
in userspace. |
| 7077 |
|
| 7078 |
- KVM_EXIT_HYPERV_SYNDBG -- synchronously notify user-space about |
| 7079 |
|
| 7080 |
Hyper-V Synthetic debugger state change. Notification is used to either update |
| 7081 |
the pending_page location or to send a control command (send the buffer located |
| 7082 |
in send_page or recv a buffer to recv_page). |
| 7083 |
|
| 7084 |
:: |
| 7085 |
|
| 7086 |
/* KVM_EXIT_ARM_NISV / KVM_EXIT_ARM_LDST64B */ |
| 7087 |
struct { |
| 7088 |
__u64 esr_iss; |
| 7089 |
__u64 fault_ipa; |
| 7090 |
} arm_nisv; |
| 7091 |
|
| 7092 |
- KVM_EXIT_ARM_NISV: |
| 7093 |
|
| 7094 |
Used on arm64 systems. If a guest accesses memory not in a memslot, |
| 7095 |
KVM will typically return to userspace and ask it to do MMIO emulation on its |
| 7096 |
behalf. However, for certain classes of instructions, no instruction decode |
| 7097 |
(direction, length of memory access) is provided, and fetching and decoding |
| 7098 |
the instruction from the VM is overly complicated to live in the kernel. |
| 7099 |
|
| 7100 |
Historically, when this situation occurred, KVM would print a warning and kill |
| 7101 |
the VM. KVM assumed that if the guest accessed non-memslot memory, it was |
| 7102 |
trying to do I/O, which just couldn't be emulated, and the warning message was |
| 7103 |
phrased accordingly. However, what happened more often was that a guest bug |
| 7104 |
caused access outside the guest memory areas which should lead to a more |
| 7105 |
meaningful warning message and an external abort in the guest, if the access |
| 7106 |
did not fall within an I/O window. |
| 7107 |
|
| 7108 |
Userspace implementations can query for KVM_CAP_ARM_NISV_TO_USER, and enable |
| 7109 |
this capability at VM creation. Once this is done, these types of errors will |
| 7110 |
instead return to userspace with KVM_EXIT_ARM_NISV, with the valid bits from |
| 7111 |
the ESR_EL2 in the esr_iss field, and the faulting IPA in the fault_ipa field. |
| 7112 |
Userspace can either fix up the access if it's actually an I/O access by |
| 7113 |
decoding the instruction from guest memory (if it's very brave) and continue |
| 7114 |
executing the guest, or it can decide to suspend, dump, or restart the guest. |
| 7115 |
|
| 7116 |
Note that KVM does not skip the faulting instruction as it does for |
| 7117 |
KVM_EXIT_MMIO, but userspace has to emulate any change to the processing state |
| 7118 |
if it decides to decode and emulate the instruction. |
| 7119 |
|
| 7120 |
This feature isn't available to protected VMs, as userspace does not |
| 7121 |
have access to the state that is required to perform the emulation. |
| 7122 |
Instead, a data abort exception is directly injected in the guest. |
| 7123 |
Note that although KVM_CAP_ARM_NISV_TO_USER will be reported if |
| 7124 |
queried outside of a protected VM context, the feature will not be |
| 7125 |
exposed if queried on a protected VM file descriptor. |
| 7126 |
|
| 7127 |
- KVM_EXIT_ARM_LDST64B: |
| 7128 |
|
| 7129 |
Used on arm64 systems. When a guest using a LD64B, ST64B, ST64BV, ST64BV0, |
| 7130 |
outside of a memslot, KVM will return to userspace with KVM_EXIT_ARM_LDST64B, |
| 7131 |
exposing the relevant ESR_EL2 information and faulting IPA, similarly to |
| 7132 |
KVM_EXIT_ARM_NISV. |
| 7133 |
|
| 7134 |
Userspace is supposed to fully emulate the instructions, which includes: |
| 7135 |
|
| 7136 |
- fetch of the operands for a store, including ACCDATA_EL1 in the case |
| 7137 |
of a ST64BV0 instruction |
| 7138 |
- deal with the endianness if the guest is big-endian |
| 7139 |
- emulate the access, including the delivery of an exception if the |
| 7140 |
access didn't succeed |
| 7141 |
- provide a return value in the case of ST64BV/ST64BV0 |
| 7142 |
- return the data in the case of a load |
| 7143 |
- increment PC if the instruction was successfully executed |
| 7144 |
|
| 7145 |
Note that there is no expectation of performance for this emulation, as it |
| 7146 |
involves a large number of interaction with the guest state. It is, however, |
| 7147 |
expected that the instruction's semantics are preserved, specially the |
| 7148 |
single-copy atomicity property of the 64 byte access. |
| 7149 |
|
| 7150 |
This exit reason must be handled if userspace sets ID_AA64ISAR1_EL1.LS64 to a |
| 7151 |
non-zero value, indicating that FEAT_LS64* is enabled. |
| 7152 |
|
| 7153 |
:: |
| 7154 |
|
| 7155 |
/* KVM_EXIT_X86_RDMSR / KVM_EXIT_X86_WRMSR */ |
| 7156 |
struct { |
| 7157 |
__u8 error; /* user -> kernel */ |
| 7158 |
__u8 pad[7]; |
| 7159 |
__u32 reason; /* kernel -> user */ |
| 7160 |
__u32 index; /* kernel -> user */ |
| 7161 |
__u64 data; /* kernel <-> user */ |
| 7162 |
} msr; |
| 7163 |
|
| 7164 |
Used on x86 systems. When the VM capability KVM_CAP_X86_USER_SPACE_MSR is |
| 7165 |
enabled, MSR accesses to registers that would invoke a #GP by KVM kernel code |
| 7166 |
may instead trigger a KVM_EXIT_X86_RDMSR exit for reads and KVM_EXIT_X86_WRMSR |
| 7167 |
exit for writes. |
| 7168 |
|
| 7169 |
The "reason" field specifies why the MSR interception occurred. Userspace will |
| 7170 |
only receive MSR exits when a particular reason was requested during through |
| 7171 |
ENABLE_CAP. Currently valid exit reasons are: |
| 7172 |
|
| 7173 |
============================ ======================================== |
| 7174 |
KVM_MSR_EXIT_REASON_UNKNOWN access to MSR that is unknown to KVM |
| 7175 |
KVM_MSR_EXIT_REASON_INVAL access to invalid MSRs or reserved bits |
| 7176 |
KVM_MSR_EXIT_REASON_FILTER access blocked by KVM_X86_SET_MSR_FILTER |
| 7177 |
============================ ======================================== |
| 7178 |
|
| 7179 |
For KVM_EXIT_X86_RDMSR, the "index" field tells userspace which MSR the guest |
| 7180 |
wants to read. To respond to this request with a successful read, userspace |
| 7181 |
writes the respective data into the "data" field and must continue guest |
| 7182 |
execution to ensure the read data is transferred into guest register state. |
| 7183 |
|
| 7184 |
If the RDMSR request was unsuccessful, userspace indicates that with a "1" in |
| 7185 |
the "error" field. This will inject a #GP into the guest when the VCPU is |
| 7186 |
executed again. |
| 7187 |
|
| 7188 |
For KVM_EXIT_X86_WRMSR, the "index" field tells userspace which MSR the guest |
| 7189 |
wants to write. Once finished processing the event, userspace must continue |
| 7190 |
vCPU execution. If the MSR write was unsuccessful, userspace also sets the |
| 7191 |
"error" field to "1". |
| 7192 |
|
| 7193 |
See KVM_X86_SET_MSR_FILTER for details on the interaction with MSR filtering. |
| 7194 |
|
| 7195 |
:: |
| 7196 |
|
| 7197 |
|
| 7198 |
struct kvm_xen_exit { |
| 7199 |
#define KVM_EXIT_XEN_HCALL 1 |
| 7200 |
__u32 type; |
| 7201 |
union { |
| 7202 |
struct { |
| 7203 |
__u32 longmode; |
| 7204 |
__u32 cpl; |
| 7205 |
__u64 input; |
| 7206 |
__u64 result; |
| 7207 |
__u64 params[6]; |
| 7208 |
} hcall; |
| 7209 |
} u; |
| 7210 |
}; |
| 7211 |
/* KVM_EXIT_XEN */ |
| 7212 |
struct kvm_hyperv_exit xen; |
| 7213 |
|
| 7214 |
Indicates that the VCPU exits into userspace to process some tasks |
| 7215 |
related to Xen emulation. |
| 7216 |
|
| 7217 |
Valid values for 'type' are: |
| 7218 |
|
| 7219 |
- KVM_EXIT_XEN_HCALL -- synchronously notify user-space about Xen hypercall. |
| 7220 |
Userspace is expected to place the hypercall result into the appropriate |
| 7221 |
field before invoking KVM_RUN again. |
| 7222 |
|
| 7223 |
:: |
| 7224 |
|
| 7225 |
/* KVM_EXIT_RISCV_SBI */ |
| 7226 |
struct { |
| 7227 |
unsigned long extension_id; |
| 7228 |
unsigned long function_id; |
| 7229 |
unsigned long args[6]; |
| 7230 |
unsigned long ret[2]; |
| 7231 |
} riscv_sbi; |
| 7232 |
|
| 7233 |
If exit reason is KVM_EXIT_RISCV_SBI then it indicates that the VCPU has |
| 7234 |
done a SBI call which is not handled by KVM RISC-V kernel module. The details |
| 7235 |
of the SBI call are available in 'riscv_sbi' member of kvm_run structure. The |
| 7236 |
'extension_id' field of 'riscv_sbi' represents SBI extension ID whereas the |
| 7237 |
'function_id' field represents function ID of given SBI extension. The 'args' |
| 7238 |
array field of 'riscv_sbi' represents parameters for the SBI call and 'ret' |
| 7239 |
array field represents return values. The userspace should update the return |
| 7240 |
values of SBI call before resuming the VCPU. For more details on RISC-V SBI |
| 7241 |
spec refer, https://github.com/riscv/riscv-sbi-doc. |
| 7242 |
|
| 7243 |
:: |
| 7244 |
|
| 7245 |
/* KVM_EXIT_MEMORY_FAULT */ |
| 7246 |
struct { |
| 7247 |
#define KVM_MEMORY_EXIT_FLAG_PRIVATE (1ULL << 3) |
| 7248 |
__u64 flags; |
| 7249 |
__u64 gpa; |
| 7250 |
__u64 size; |
| 7251 |
} memory_fault; |
| 7252 |
|
| 7253 |
KVM_EXIT_MEMORY_FAULT indicates the vCPU has encountered a memory fault that |
| 7254 |
could not be resolved by KVM. The 'gpa' and 'size' (in bytes) describe the |
| 7255 |
guest physical address range [gpa, gpa + size) of the fault. The 'flags' field |
| 7256 |
describes properties of the faulting access that are likely pertinent: |
| 7257 |
|
| 7258 |
- KVM_MEMORY_EXIT_FLAG_PRIVATE - When set, indicates the memory fault occurred |
| 7259 |
on a private memory access. When clear, indicates the fault occurred on a |
| 7260 |
shared access. |
| 7261 |
|
| 7262 |
Note! KVM_EXIT_MEMORY_FAULT is unique among all KVM exit reasons in that it |
| 7263 |
accompanies a return code of '-1', not '0'! errno will always be set to EFAULT |
| 7264 |
or EHWPOISON when KVM exits with KVM_EXIT_MEMORY_FAULT, userspace should assume |
| 7265 |
kvm_run.exit_reason is stale/undefined for all other error numbers. |
| 7266 |
|
| 7267 |
:: |
| 7268 |
|
| 7269 |
/* KVM_EXIT_NOTIFY */ |
| 7270 |
struct { |
| 7271 |
#define KVM_NOTIFY_CONTEXT_INVALID (1 << 0) |
| 7272 |
__u32 flags; |
| 7273 |
} notify; |
| 7274 |
|
| 7275 |
Used on x86 systems. When the VM capability KVM_CAP_X86_NOTIFY_VMEXIT is |
| 7276 |
enabled, a VM exit generated if no event window occurs in VM non-root mode |
| 7277 |
for a specified amount of time. Once KVM_X86_NOTIFY_VMEXIT_USER is set when |
| 7278 |
enabling the cap, it would exit to userspace with the exit reason |
| 7279 |
KVM_EXIT_NOTIFY for further handling. The "flags" field contains more |
| 7280 |
detailed info. |
| 7281 |
|
| 7282 |
The valid value for 'flags' is: |
| 7283 |
|
| 7284 |
- KVM_NOTIFY_CONTEXT_INVALID -- the VM context is corrupted and not valid |
| 7285 |
in VMCS. It would run into unknown result if resume the target VM. |
| 7286 |
|
| 7287 |
:: |
| 7288 |
|
| 7289 |
/* KVM_EXIT_TDX */ |
| 7290 |
struct { |
| 7291 |
__u64 flags; |
| 7292 |
__u64 nr; |
| 7293 |
union { |
| 7294 |
struct { |
| 7295 |
u64 ret; |
| 7296 |
u64 data[5]; |
| 7297 |
} unknown; |
| 7298 |
struct { |
| 7299 |
u64 ret; |
| 7300 |
u64 gpa; |
| 7301 |
u64 size; |
| 7302 |
} get_quote; |
| 7303 |
struct { |
| 7304 |
u64 ret; |
| 7305 |
u64 leaf; |
| 7306 |
u64 r11, r12, r13, r14; |
| 7307 |
} get_tdvmcall_info; |
| 7308 |
struct { |
| 7309 |
u64 ret; |
| 7310 |
u64 vector; |
| 7311 |
} setup_event_notify; |
| 7312 |
}; |
| 7313 |
} tdx; |
| 7314 |
|
| 7315 |
Process a TDVMCALL from the guest. KVM forwards select TDVMCALL based |
| 7316 |
on the Guest-Hypervisor Communication Interface (GHCI) specification; |
| 7317 |
KVM bridges these requests to the userspace VMM with minimal changes, |
| 7318 |
placing the inputs in the union and copying them back to the guest |
| 7319 |
on re-entry. |
| 7320 |
|
| 7321 |
Flags are currently always zero, whereas ``nr`` contains the TDVMCALL |
| 7322 |
number from register R11. The remaining field of the union provide the |
| 7323 |
inputs and outputs of the TDVMCALL. Currently the following values of |
| 7324 |
``nr`` are defined: |
| 7325 |
|
| 7326 |
* ``TDVMCALL_GET_QUOTE``: the guest has requested to generate a TD-Quote |
| 7327 |
signed by a service hosting TD-Quoting Enclave operating on the host. |
| 7328 |
Parameters and return value are in the ``get_quote`` field of the union. |
| 7329 |
The ``gpa`` field and ``size`` specify the guest physical address |
| 7330 |
(without the shared bit set) and the size of a shared-memory buffer, in |
| 7331 |
which the TDX guest passes a TD Report. The ``ret`` field represents |
| 7332 |
the return value of the GetQuote request. When the request has been |
| 7333 |
queued successfully, the TDX guest can poll the status field in the |
| 7334 |
shared-memory area to check whether the Quote generation is completed or |
| 7335 |
not. When completed, the generated Quote is returned via the same buffer. |
| 7336 |
|
| 7337 |
* ``TDVMCALL_GET_TD_VM_CALL_INFO``: the guest has requested the support |
| 7338 |
status of TDVMCALLs. The output values for the given leaf should be |
| 7339 |
placed in fields from ``r11`` to ``r14`` of the ``get_tdvmcall_info`` |
| 7340 |
field of the union. |
| 7341 |
|
| 7342 |
* ``TDVMCALL_SETUP_EVENT_NOTIFY_INTERRUPT``: the guest has requested to |
| 7343 |
set up a notification interrupt for vector ``vector``. |
| 7344 |
|
| 7345 |
KVM may add support for more values in the future that may cause a userspace |
| 7346 |
exit, even without calls to ``KVM_ENABLE_CAP`` or similar. In this case, |
| 7347 |
it will enter with output fields already valid; in the common case, the |
| 7348 |
``unknown.ret`` field of the union will be ``TDVMCALL_STATUS_SUBFUNC_UNSUPPORTED``. |
| 7349 |
Userspace need not do anything if it does not wish to support a TDVMCALL. |
| 7350 |
|
| 7351 |
:: |
| 7352 |
|
| 7353 |
/* KVM_EXIT_ARM_SEA */ |
| 7354 |
struct { |
| 7355 |
#define KVM_EXIT_ARM_SEA_FLAG_GPA_VALID (1ULL << 0) |
| 7356 |
__u64 flags; |
| 7357 |
__u64 esr; |
| 7358 |
__u64 gva; |
| 7359 |
__u64 gpa; |
| 7360 |
} arm_sea; |
| 7361 |
|
| 7362 |
Used on arm64 systems. When the VM capability ``KVM_CAP_ARM_SEA_TO_USER`` is |
| 7363 |
enabled, a KVM exits to userspace if a guest access causes a synchronous |
| 7364 |
external abort (SEA) and the host APEI fails to handle the SEA. |
| 7365 |
|
| 7366 |
``esr`` is set to a sanitized value of ESR_EL2 from the exception taken to KVM, |
| 7367 |
consisting of the following fields: |
| 7368 |
|
| 7369 |
- ``ESR_EL2.EC`` |
| 7370 |
- ``ESR_EL2.IL`` |
| 7371 |
- ``ESR_EL2.FnV`` |
| 7372 |
- ``ESR_EL2.EA`` |
| 7373 |
- ``ESR_EL2.CM`` |
| 7374 |
- ``ESR_EL2.WNR`` |
| 7375 |
- ``ESR_EL2.FSC`` |
| 7376 |
- ``ESR_EL2.SET`` (when FEAT_RAS is implemented for the VM) |
| 7377 |
|
| 7378 |
``gva`` is set to the value of FAR_EL2 from the exception taken to KVM when |
| 7379 |
``ESR_EL2.FnV == 0``. Otherwise, the value of ``gva`` is unknown. |
| 7380 |
|
| 7381 |
``gpa`` is set to the faulting IPA from the exception taken to KVM when |
| 7382 |
the ``KVM_EXIT_ARM_SEA_FLAG_GPA_VALID`` flag is set. Otherwise, the value of |
| 7383 |
``gpa`` is unknown. |
| 7384 |
|
| 7385 |
:: |
| 7386 |
|
| 7387 |
/* Fix the size of the union. */ |
| 7388 |
char padding[256]; |
| 7389 |
}; |
| 7390 |
|
| 7391 |
/* |
| 7392 |
* shared registers between kvm and userspace. |
| 7393 |
* kvm_valid_regs specifies the register classes set by the host |
| 7394 |
* kvm_dirty_regs specified the register classes dirtied by userspace |
| 7395 |
* struct kvm_sync_regs is architecture specific, as well as the |
| 7396 |
* bits for kvm_valid_regs and kvm_dirty_regs |
| 7397 |
*/ |
| 7398 |
__u64 kvm_valid_regs; |
| 7399 |
__u64 kvm_dirty_regs; |
| 7400 |
union { |
| 7401 |
struct kvm_sync_regs regs; |
| 7402 |
char padding[SYNC_REGS_SIZE_BYTES]; |
| 7403 |
} s; |
| 7404 |
|
| 7405 |
If KVM_CAP_SYNC_REGS is defined, these fields allow userspace to access |
| 7406 |
certain guest registers without having to call SET/GET_*REGS. Thus we can |
| 7407 |
avoid some system call overhead if userspace has to handle the exit. |
| 7408 |
Userspace can query the validity of the structure by checking |
| 7409 |
kvm_valid_regs for specific bits. These bits are architecture specific |
| 7410 |
and usually define the validity of a groups of registers. (e.g. one bit |
| 7411 |
for general purpose registers) |
| 7412 |
|
| 7413 |
Please note that the kernel is allowed to use the kvm_run structure as the |
| 7414 |
primary storage for certain register types. Therefore, the kernel may use the |
| 7415 |
values in kvm_run even if the corresponding bit in kvm_dirty_regs is not set. |
| 7416 |
|
| 7417 |
:: |
| 7418 |
|
| 7419 |
/* KVM_EXIT_SNP_REQ_CERTS */ |
| 7420 |
struct kvm_exit_snp_req_certs { |
| 7421 |
__u64 gpa; |
| 7422 |
__u64 npages; |
| 7423 |
__u64 ret; |
| 7424 |
}; |
| 7425 |
|
| 7426 |
KVM_EXIT_SNP_REQ_CERTS indicates an SEV-SNP guest with certificate-fetching |
| 7427 |
enabled (see KVM_SEV_SNP_ENABLE_REQ_CERTS) has generated an Extended Guest |
| 7428 |
Request NAE #VMGEXIT (SNP_GUEST_REQUEST) with message type MSG_REPORT_REQ, |
| 7429 |
i.e. has requested an attestation report from firmware, and would like the |
| 7430 |
certificate data corresponding to the attestation report signature to be |
| 7431 |
provided by the hypervisor as part of the request. |
| 7432 |
|
| 7433 |
To allow for userspace to provide the certificate, the 'gpa' and 'npages' |
| 7434 |
are forwarded verbatim from the guest request (the RAX and RBX GHCB fields |
| 7435 |
respectively). 'ret' is not an "output" from KVM, and is always '0' on |
| 7436 |
exit. KVM verifies the 'gpa' is 4KiB aligned prior to exiting to userspace, |
| 7437 |
but otherwise the information from the guest isn't validated. |
| 7438 |
|
| 7439 |
Upon the next KVM_RUN, e.g. after userspace has serviced the request (or not), |
| 7440 |
KVM will complete the #VMGEXIT, using the 'ret' field to determine whether to |
| 7441 |
signal success or failure to the guest, and on failure, what reason code will |
| 7442 |
be communicated via SW_EXITINFO2. If 'ret' is set to an unsupported value (see |
| 7443 |
the table below), KVM_RUN will fail with -EINVAL. For a 'ret' of 'ENOSPC', KVM |
| 7444 |
also consumes the 'npages' field, i.e. userspace can use the field to inform |
| 7445 |
the guest of the number of pages needed to hold all the certificate data. |
| 7446 |
|
| 7447 |
The supported 'ret' values and their respective SW_EXITINFO2 encodings: |
| 7448 |
|
| 7449 |
====== ============================================================= |
| 7450 |
0 0x0, i.e. success. KVM will emit an SNP_GUEST_REQUEST command |
| 7451 |
to SNP firmware. |
| 7452 |
ENOSPC 0x0000000100000000, i.e. not enough guest pages to hold the |
| 7453 |
certificate table and certificate data. KVM will also set the |
| 7454 |
RBX field in the GHBC to 'npages'. |
| 7455 |
EAGAIN 0x0000000200000000, i.e. the host is busy and the guest should |
| 7456 |
retry the request. |
| 7457 |
EIO 0xffffffff00000000, for all other errors (this return code is |
| 7458 |
a KVM-defined hypervisor value, as allowed by the GHCB) |
| 7459 |
====== ============================================================= |
| 7460 |
|
| 7461 |
|
| 7462 |
.. _cap_enable: |
| 7463 |
|
| 7464 |
6. Capabilities that can be enabled on vCPUs |
| 7465 |
============================================ |
| 7466 |
|
| 7467 |
There are certain capabilities that change the behavior of the virtual CPU or |
| 7468 |
the virtual machine when enabled. To enable them, please see |
| 7469 |
:ref:`KVM_ENABLE_CAP`. |
| 7470 |
|
| 7471 |
Below you can find a list of capabilities and what their effect on the vCPU or |
| 7472 |
the virtual machine is when enabling them. |
| 7473 |
|
| 7474 |
The following information is provided along with the description: |
| 7475 |
|
| 7476 |
Architectures: |
| 7477 |
which instruction set architectures provide this ioctl. |
| 7478 |
x86 includes both i386 and x86_64. |
| 7479 |
|
| 7480 |
Target: |
| 7481 |
whether this is a per-vcpu or per-vm capability. |
| 7482 |
|
| 7483 |
Parameters: |
| 7484 |
what parameters are accepted by the capability. |
| 7485 |
|
| 7486 |
Returns: |
| 7487 |
the return value. General error numbers (EBADF, ENOMEM, EINVAL) |
| 7488 |
are not detailed, but errors with specific meanings are. |
| 7489 |
|
| 7490 |
|
| 7491 |
6.1 KVM_CAP_PPC_OSI |
| 7492 |
------------------- |
| 7493 |
|
| 7494 |
:Architectures: ppc |
| 7495 |
:Target: vcpu |
| 7496 |
:Parameters: none |
| 7497 |
:Returns: 0 on success; -1 on error |
| 7498 |
|
| 7499 |
This capability enables interception of OSI hypercalls that otherwise would |
| 7500 |
be treated as normal system calls to be injected into the guest. OSI hypercalls |
| 7501 |
were invented by Mac-on-Linux to have a standardized communication mechanism |
| 7502 |
between the guest and the host. |
| 7503 |
|
| 7504 |
When this capability is enabled, KVM_EXIT_OSI can occur. |
| 7505 |
|
| 7506 |
|
| 7507 |
6.2 KVM_CAP_PPC_PAPR |
| 7508 |
-------------------- |
| 7509 |
|
| 7510 |
:Architectures: ppc |
| 7511 |
:Target: vcpu |
| 7512 |
:Parameters: none |
| 7513 |
:Returns: 0 on success; -1 on error |
| 7514 |
|
| 7515 |
This capability enables interception of PAPR hypercalls. PAPR hypercalls are |
| 7516 |
done using the hypercall instruction "sc 1". |
| 7517 |
|
| 7518 |
It also sets the guest privilege level to "supervisor" mode. Usually the guest |
| 7519 |
runs in "hypervisor" privilege mode with a few missing features. |
| 7520 |
|
| 7521 |
In addition to the above, it changes the semantics of SDR1. In this mode, the |
| 7522 |
HTAB address part of SDR1 contains an HVA instead of a GPA, as PAPR keeps the |
| 7523 |
HTAB invisible to the guest. |
| 7524 |
|
| 7525 |
When this capability is enabled, KVM_EXIT_PAPR_HCALL can occur. |
| 7526 |
|
| 7527 |
|
| 7528 |
6.3 KVM_CAP_SW_TLB |
| 7529 |
------------------ |
| 7530 |
|
| 7531 |
:Architectures: ppc |
| 7532 |
:Target: vcpu |
| 7533 |
:Parameters: args[0] is the address of a struct kvm_config_tlb |
| 7534 |
:Returns: 0 on success; -1 on error |
| 7535 |
|
| 7536 |
:: |
| 7537 |
|
| 7538 |
struct kvm_config_tlb { |
| 7539 |
__u64 params; |
| 7540 |
__u64 array; |
| 7541 |
__u32 mmu_type; |
| 7542 |
__u32 array_len; |
| 7543 |
}; |
| 7544 |
|
| 7545 |
Configures the virtual CPU's TLB array, establishing a shared memory area |
| 7546 |
between userspace and KVM. The "params" and "array" fields are userspace |
| 7547 |
addresses of mmu-type-specific data structures. The "array_len" field is an |
| 7548 |
safety mechanism, and should be set to the size in bytes of the memory that |
| 7549 |
userspace has reserved for the array. It must be at least the size dictated |
| 7550 |
by "mmu_type" and "params". |
| 7551 |
|
| 7552 |
While KVM_RUN is active, the shared region is under control of KVM. Its |
| 7553 |
contents are undefined, and any modification by userspace results in |
| 7554 |
boundedly undefined behavior. |
| 7555 |
|
| 7556 |
On return from KVM_RUN, the shared region will reflect the current state of |
| 7557 |
the guest's TLB. If userspace makes any changes, it must call KVM_DIRTY_TLB |
| 7558 |
to tell KVM which entries have been changed, prior to calling KVM_RUN again |
| 7559 |
on this vcpu. |
| 7560 |
|
| 7561 |
For mmu types KVM_MMU_FSL_BOOKE_NOHV and KVM_MMU_FSL_BOOKE_HV: |
| 7562 |
|
| 7563 |
- The "params" field is of type "struct kvm_book3e_206_tlb_params". |
| 7564 |
- The "array" field points to an array of type "struct |
| 7565 |
kvm_book3e_206_tlb_entry". |
| 7566 |
- The array consists of all entries in the first TLB, followed by all |
| 7567 |
entries in the second TLB. |
| 7568 |
- Within a TLB, entries are ordered first by increasing set number. Within a |
| 7569 |
set, entries are ordered by way (increasing ESEL). |
| 7570 |
- The hash for determining set number in TLB0 is: (MAS2 >> 12) & (num_sets - 1) |
| 7571 |
where "num_sets" is the tlb_sizes[] value divided by the tlb_ways[] value. |
| 7572 |
- The tsize field of mas1 shall be set to 4K on TLB0, even though the |
| 7573 |
hardware ignores this value for TLB0. |
| 7574 |
|
| 7575 |
6.4 KVM_CAP_S390_CSS_SUPPORT |
| 7576 |
---------------------------- |
| 7577 |
|
| 7578 |
:Architectures: s390 |
| 7579 |
:Target: vcpu |
| 7580 |
:Parameters: none |
| 7581 |
:Returns: 0 on success; -1 on error |
| 7582 |
|
| 7583 |
This capability enables support for handling of channel I/O instructions. |
| 7584 |
|
| 7585 |
TEST PENDING INTERRUPTION and the interrupt portion of TEST SUBCHANNEL are |
| 7586 |
handled in-kernel, while the other I/O instructions are passed to userspace. |
| 7587 |
|
| 7588 |
When this capability is enabled, KVM_EXIT_S390_TSCH will occur on TEST |
| 7589 |
SUBCHANNEL intercepts. |
| 7590 |
|
| 7591 |
Note that even though this capability is enabled per-vcpu, the complete |
| 7592 |
virtual machine is affected. |
| 7593 |
|
| 7594 |
6.5 KVM_CAP_PPC_EPR |
| 7595 |
------------------- |
| 7596 |
|
| 7597 |
:Architectures: ppc |
| 7598 |
:Target: vcpu |
| 7599 |
:Parameters: args[0] defines whether the proxy facility is active |
| 7600 |
:Returns: 0 on success; -1 on error |
| 7601 |
|
| 7602 |
This capability enables or disables the delivery of interrupts through the |
| 7603 |
external proxy facility. |
| 7604 |
|
| 7605 |
When enabled (args[0] != 0), every time the guest gets an external interrupt |
| 7606 |
delivered, it automatically exits into user space with a KVM_EXIT_EPR exit |
| 7607 |
to receive the topmost interrupt vector. |
| 7608 |
|
| 7609 |
When disabled (args[0] == 0), behavior is as if this facility is unsupported. |
| 7610 |
|
| 7611 |
When this capability is enabled, KVM_EXIT_EPR can occur. |
| 7612 |
|
| 7613 |
6.6 KVM_CAP_IRQ_MPIC |
| 7614 |
-------------------- |
| 7615 |
|
| 7616 |
:Architectures: ppc |
| 7617 |
:Parameters: args[0] is the MPIC device fd; |
| 7618 |
args[1] is the MPIC CPU number for this vcpu |
| 7619 |
|
| 7620 |
This capability connects the vcpu to an in-kernel MPIC device. |
| 7621 |
|
| 7622 |
6.7 KVM_CAP_IRQ_XICS |
| 7623 |
-------------------- |
| 7624 |
|
| 7625 |
:Architectures: ppc |
| 7626 |
:Target: vcpu |
| 7627 |
:Parameters: args[0] is the XICS device fd; |
| 7628 |
args[1] is the XICS CPU number (server ID) for this vcpu |
| 7629 |
|
| 7630 |
This capability connects the vcpu to an in-kernel XICS device. |
| 7631 |
|
| 7632 |
6.8 KVM_CAP_S390_IRQCHIP |
| 7633 |
------------------------ |
| 7634 |
|
| 7635 |
:Architectures: s390 |
| 7636 |
:Target: vm |
| 7637 |
:Parameters: none |
| 7638 |
|
| 7639 |
This capability enables the in-kernel irqchip for s390. Please refer to |
| 7640 |
"4.24 KVM_CREATE_IRQCHIP" for details. |
| 7641 |
|
| 7642 |
6.9 KVM_CAP_MIPS_FPU |
| 7643 |
-------------------- |
| 7644 |
|
| 7645 |
:Architectures: mips |
| 7646 |
:Target: vcpu |
| 7647 |
:Parameters: args[0] is reserved for future use (should be 0). |
| 7648 |
|
| 7649 |
This capability allows the use of the host Floating Point Unit by the guest. It |
| 7650 |
allows the Config1.FP bit to be set to enable the FPU in the guest. Once this is |
| 7651 |
done the ``KVM_REG_MIPS_FPR_*`` and ``KVM_REG_MIPS_FCR_*`` registers can be |
| 7652 |
accessed (depending on the current guest FPU register mode), and the Status.FR, |
| 7653 |
Config5.FRE bits are accessible via the KVM API and also from the guest, |
| 7654 |
depending on them being supported by the FPU. |
| 7655 |
|
| 7656 |
6.10 KVM_CAP_MIPS_MSA |
| 7657 |
--------------------- |
| 7658 |
|
| 7659 |
:Architectures: mips |
| 7660 |
:Target: vcpu |
| 7661 |
:Parameters: args[0] is reserved for future use (should be 0). |
| 7662 |
|
| 7663 |
This capability allows the use of the MIPS SIMD Architecture (MSA) by the guest. |
| 7664 |
It allows the Config3.MSAP bit to be set to enable the use of MSA by the guest. |
| 7665 |
Once this is done the ``KVM_REG_MIPS_VEC_*`` and ``KVM_REG_MIPS_MSA_*`` |
| 7666 |
registers can be accessed, and the Config5.MSAEn bit is accessible via the |
| 7667 |
KVM API and also from the guest. |
| 7668 |
|
| 7669 |
6.74 KVM_CAP_SYNC_REGS |
| 7670 |
---------------------- |
| 7671 |
|
| 7672 |
:Architectures: s390, x86 |
| 7673 |
:Target: s390: always enabled, x86: vcpu |
| 7674 |
:Parameters: none |
| 7675 |
:Returns: x86: KVM_CHECK_EXTENSION returns a bit-array indicating which register |
| 7676 |
sets are supported |
| 7677 |
(bitfields defined in arch/x86/include/uapi/asm/kvm.h). |
| 7678 |
|
| 7679 |
As described above in the kvm_sync_regs struct info in section :ref:`kvm_run`, |
| 7680 |
KVM_CAP_SYNC_REGS "allow[s] userspace to access certain guest registers |
| 7681 |
without having to call SET/GET_*REGS". This reduces overhead by eliminating |
| 7682 |
repeated ioctl calls for setting and/or getting register values. This is |
| 7683 |
particularly important when userspace is making synchronous guest state |
| 7684 |
modifications, e.g. when emulating and/or intercepting instructions in |
| 7685 |
userspace. |
| 7686 |
|
| 7687 |
For s390 specifics, please refer to the source code. |
| 7688 |
|
| 7689 |
For x86: |
| 7690 |
|
| 7691 |
- the register sets to be copied out to kvm_run are selectable |
| 7692 |
by userspace (rather that all sets being copied out for every exit). |
| 7693 |
- vcpu_events are available in addition to regs and sregs. |
| 7694 |
|
| 7695 |
For x86, the 'kvm_valid_regs' field of struct kvm_run is overloaded to |
| 7696 |
function as an input bit-array field set by userspace to indicate the |
| 7697 |
specific register sets to be copied out on the next exit. |
| 7698 |
|
| 7699 |
To indicate when userspace has modified values that should be copied into |
| 7700 |
the vCPU, the all architecture bitarray field, 'kvm_dirty_regs' must be set. |
| 7701 |
This is done using the same bitflags as for the 'kvm_valid_regs' field. |
| 7702 |
If the dirty bit is not set, then the register set values will not be copied |
| 7703 |
into the vCPU even if they've been modified. |
| 7704 |
|
| 7705 |
Unused bitfields in the bitarrays must be set to zero. |
| 7706 |
|
| 7707 |
:: |
| 7708 |
|
| 7709 |
struct kvm_sync_regs { |
| 7710 |
struct kvm_regs regs; |
| 7711 |
struct kvm_sregs sregs; |
| 7712 |
struct kvm_vcpu_events events; |
| 7713 |
}; |
| 7714 |
|
| 7715 |
6.75 KVM_CAP_PPC_IRQ_XIVE |
| 7716 |
------------------------- |
| 7717 |
|
| 7718 |
:Architectures: ppc |
| 7719 |
:Target: vcpu |
| 7720 |
:Parameters: args[0] is the XIVE device fd; |
| 7721 |
args[1] is the XIVE CPU number (server ID) for this vcpu |
| 7722 |
|
| 7723 |
This capability connects the vcpu to an in-kernel XIVE device. |
| 7724 |
|
| 7725 |
6.76 KVM_CAP_HYPERV_SYNIC |
| 7726 |
------------------------- |
| 7727 |
|
| 7728 |
:Architectures: x86 |
| 7729 |
:Target: vcpu |
| 7730 |
|
| 7731 |
This capability, if KVM_CHECK_EXTENSION indicates that it is |
| 7732 |
available, means that the kernel has an implementation of the |
| 7733 |
Hyper-V Synthetic interrupt controller(SynIC). Hyper-V SynIC is |
| 7734 |
used to support Windows Hyper-V based guest paravirt drivers(VMBus). |
| 7735 |
|
| 7736 |
In order to use SynIC, it has to be activated by setting this |
| 7737 |
capability via KVM_ENABLE_CAP ioctl on the vcpu fd. Note that this |
| 7738 |
will disable the use of APIC hardware virtualization even if supported |
| 7739 |
by the CPU, as it's incompatible with SynIC auto-EOI behavior. |
| 7740 |
|
| 7741 |
6.77 KVM_CAP_HYPERV_SYNIC2 |
| 7742 |
-------------------------- |
| 7743 |
|
| 7744 |
:Architectures: x86 |
| 7745 |
:Target: vcpu |
| 7746 |
|
| 7747 |
This capability enables a newer version of Hyper-V Synthetic interrupt |
| 7748 |
controller (SynIC). The only difference with KVM_CAP_HYPERV_SYNIC is that KVM |
| 7749 |
doesn't clear SynIC message and event flags pages when they are enabled by |
| 7750 |
writing to the respective MSRs. |
| 7751 |
|
| 7752 |
6.78 KVM_CAP_HYPERV_DIRECT_TLBFLUSH |
| 7753 |
----------------------------------- |
| 7754 |
|
| 7755 |
:Architectures: x86 |
| 7756 |
:Target: vcpu |
| 7757 |
|
| 7758 |
This capability indicates that KVM running on top of Hyper-V hypervisor |
| 7759 |
enables Direct TLB flush for its guests meaning that TLB flush |
| 7760 |
hypercalls are handled by Level 0 hypervisor (Hyper-V) bypassing KVM. |
| 7761 |
Due to the different ABI for hypercall parameters between Hyper-V and |
| 7762 |
KVM, enabling this capability effectively disables all hypercall |
| 7763 |
handling by KVM (as some KVM hypercall may be mistakenly treated as TLB |
| 7764 |
flush hypercalls by Hyper-V) so userspace should disable KVM identification |
| 7765 |
in CPUID and only exposes Hyper-V identification. In this case, guest |
| 7766 |
thinks it's running on Hyper-V and only use Hyper-V hypercalls. |
| 7767 |
|
| 7768 |
6.79 KVM_CAP_HYPERV_ENFORCE_CPUID |
| 7769 |
--------------------------------- |
| 7770 |
|
| 7771 |
:Architectures: x86 |
| 7772 |
:Target: vcpu |
| 7773 |
|
| 7774 |
When enabled, KVM will disable emulated Hyper-V features provided to the |
| 7775 |
guest according to the bits Hyper-V CPUID feature leaves. Otherwise, all |
| 7776 |
currently implemented Hyper-V features are provided unconditionally when |
| 7777 |
Hyper-V identification is set in the HYPERV_CPUID_INTERFACE (0x40000001) |
| 7778 |
leaf. |
| 7779 |
|
| 7780 |
6.80 KVM_CAP_ENFORCE_PV_FEATURE_CPUID |
| 7781 |
------------------------------------- |
| 7782 |
|
| 7783 |
:Architectures: x86 |
| 7784 |
:Target: vcpu |
| 7785 |
|
| 7786 |
When enabled, KVM will disable paravirtual features provided to the |
| 7787 |
guest according to the bits in the KVM_CPUID_FEATURES CPUID leaf |
| 7788 |
(0x40000001). Otherwise, a guest may use the paravirtual features |
| 7789 |
regardless of what has actually been exposed through the CPUID leaf. |
| 7790 |
|
| 7791 |
.. _KVM_CAP_DIRTY_LOG_RING: |
| 7792 |
|
| 7793 |
|
| 7794 |
.. _cap_enable_vm: |
| 7795 |
|
| 7796 |
7. Capabilities that can be enabled on VMs |
| 7797 |
========================================== |
| 7798 |
|
| 7799 |
There are certain capabilities that change the behavior of the virtual |
| 7800 |
machine when enabled. To enable them, please see section |
| 7801 |
:ref:`KVM_ENABLE_CAP`. Below you can find a list of capabilities and |
| 7802 |
what their effect on the VM is when enabling them. |
| 7803 |
|
| 7804 |
The following information is provided along with the description: |
| 7805 |
|
| 7806 |
Architectures: |
| 7807 |
which instruction set architectures provide this ioctl. |
| 7808 |
x86 includes both i386 and x86_64. |
| 7809 |
|
| 7810 |
Parameters: |
| 7811 |
what parameters are accepted by the capability. |
| 7812 |
|
| 7813 |
Returns: |
| 7814 |
the return value. General error numbers (EBADF, ENOMEM, EINVAL) |
| 7815 |
are not detailed, but errors with specific meanings are. |
| 7816 |
|
| 7817 |
|
| 7818 |
7.1 KVM_CAP_PPC_ENABLE_HCALL |
| 7819 |
---------------------------- |
| 7820 |
|
| 7821 |
:Architectures: ppc |
| 7822 |
:Parameters: args[0] is the sPAPR hcall number; |
| 7823 |
args[1] is 0 to disable, 1 to enable in-kernel handling |
| 7824 |
|
| 7825 |
This capability controls whether individual sPAPR hypercalls (hcalls) |
| 7826 |
get handled by the kernel or not. Enabling or disabling in-kernel |
| 7827 |
handling of an hcall is effective across the VM. On creation, an |
| 7828 |
initial set of hcalls are enabled for in-kernel handling, which |
| 7829 |
consists of those hcalls for which in-kernel handlers were implemented |
| 7830 |
before this capability was implemented. If disabled, the kernel will |
| 7831 |
not to attempt to handle the hcall, but will always exit to userspace |
| 7832 |
to handle it. Note that it may not make sense to enable some and |
| 7833 |
disable others of a group of related hcalls, but KVM does not prevent |
| 7834 |
userspace from doing that. |
| 7835 |
|
| 7836 |
If the hcall number specified is not one that has an in-kernel |
| 7837 |
implementation, the KVM_ENABLE_CAP ioctl will fail with an EINVAL |
| 7838 |
error. |
| 7839 |
|
| 7840 |
7.2 KVM_CAP_S390_USER_SIGP |
| 7841 |
-------------------------- |
| 7842 |
|
| 7843 |
:Architectures: s390 |
| 7844 |
:Parameters: none |
| 7845 |
|
| 7846 |
This capability controls which SIGP orders will be handled completely in user |
| 7847 |
space. With this capability enabled, all fast orders will be handled completely |
| 7848 |
in the kernel: |
| 7849 |
|
| 7850 |
- SENSE |
| 7851 |
- SENSE RUNNING |
| 7852 |
- EXTERNAL CALL |
| 7853 |
- EMERGENCY SIGNAL |
| 7854 |
- CONDITIONAL EMERGENCY SIGNAL |
| 7855 |
|
| 7856 |
All other orders will be handled completely in user space. |
| 7857 |
|
| 7858 |
Only privileged operation exceptions will be checked for in the kernel (or even |
| 7859 |
in the hardware prior to interception). If this capability is not enabled, the |
| 7860 |
old way of handling SIGP orders is used (partially in kernel and user space). |
| 7861 |
|
| 7862 |
7.3 KVM_CAP_S390_VECTOR_REGISTERS |
| 7863 |
--------------------------------- |
| 7864 |
|
| 7865 |
:Architectures: s390 |
| 7866 |
:Parameters: none |
| 7867 |
:Returns: 0 on success, negative value on error |
| 7868 |
|
| 7869 |
Allows use of the vector registers introduced with z13 processor, and |
| 7870 |
provides for the synchronization between host and user space. Will |
| 7871 |
return -EINVAL if the machine does not support vectors. |
| 7872 |
|
| 7873 |
7.4 KVM_CAP_S390_USER_STSI |
| 7874 |
-------------------------- |
| 7875 |
|
| 7876 |
:Architectures: s390 |
| 7877 |
:Parameters: none |
| 7878 |
|
| 7879 |
This capability allows post-handlers for the STSI instruction. After |
| 7880 |
initial handling in the kernel, KVM exits to user space with |
| 7881 |
KVM_EXIT_S390_STSI to allow user space to insert further data. |
| 7882 |
|
| 7883 |
Before exiting to userspace, kvm handlers should fill in s390_stsi field of |
| 7884 |
vcpu->run:: |
| 7885 |
|
| 7886 |
struct { |
| 7887 |
__u64 addr; |
| 7888 |
__u8 ar; |
| 7889 |
__u8 reserved; |
| 7890 |
__u8 fc; |
| 7891 |
__u8 sel1; |
| 7892 |
__u16 sel2; |
| 7893 |
} s390_stsi; |
| 7894 |
|
| 7895 |
@addr - guest address of STSI SYSIB |
| 7896 |
@fc - function code |
| 7897 |
@sel1 - selector 1 |
| 7898 |
@sel2 - selector 2 |
| 7899 |
@ar - access register number |
| 7900 |
|
| 7901 |
KVM handlers should exit to userspace with rc = -EREMOTE. |
| 7902 |
|
| 7903 |
7.5 KVM_CAP_SPLIT_IRQCHIP |
| 7904 |
------------------------- |
| 7905 |
|
| 7906 |
:Architectures: x86 |
| 7907 |
:Parameters: args[0] - number of routes reserved for userspace IOAPICs |
| 7908 |
:Returns: 0 on success, -1 on error |
| 7909 |
|
| 7910 |
Create a local apic for each processor in the kernel. This can be used |
| 7911 |
instead of KVM_CREATE_IRQCHIP if the userspace VMM wishes to emulate the |
| 7912 |
IOAPIC and PIC (and also the PIT, even though this has to be enabled |
| 7913 |
separately). |
| 7914 |
|
| 7915 |
This capability also enables in kernel routing of interrupt requests; |
| 7916 |
when KVM_CAP_SPLIT_IRQCHIP only routes of KVM_IRQ_ROUTING_MSI type are |
| 7917 |
used in the IRQ routing table. The first args[0] MSI routes are reserved |
| 7918 |
for the IOAPIC pins. Whenever the LAPIC receives an EOI for these routes, |
| 7919 |
a KVM_EXIT_IOAPIC_EOI vmexit will be reported to userspace. |
| 7920 |
|
| 7921 |
Fails if VCPU has already been created, or if the irqchip is already in the |
| 7922 |
kernel (i.e. KVM_CREATE_IRQCHIP has already been called). |
| 7923 |
|
| 7924 |
7.6 KVM_CAP_S390_RI |
| 7925 |
------------------- |
| 7926 |
|
| 7927 |
:Architectures: s390 |
| 7928 |
:Parameters: none |
| 7929 |
|
| 7930 |
Allows use of runtime-instrumentation introduced with zEC12 processor. |
| 7931 |
Will return -EINVAL if the machine does not support runtime-instrumentation. |
| 7932 |
Will return -EBUSY if a VCPU has already been created. |
| 7933 |
|
| 7934 |
7.7 KVM_CAP_X2APIC_API |
| 7935 |
---------------------- |
| 7936 |
|
| 7937 |
:Architectures: x86 |
| 7938 |
:Parameters: args[0] - features that should be enabled |
| 7939 |
:Returns: 0 on success, -EINVAL when args[0] contains invalid features |
| 7940 |
|
| 7941 |
Valid feature flags in args[0] are:: |
| 7942 |
|
| 7943 |
#define KVM_X2APIC_API_USE_32BIT_IDS (1ULL << 0) |
| 7944 |
#define KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK (1ULL << 1) |
| 7945 |
#define KVM_X2APIC_ENABLE_SUPPRESS_EOI_BROADCAST (1ULL << 2) |
| 7946 |
#define KVM_X2APIC_DISABLE_SUPPRESS_EOI_BROADCAST (1ULL << 3) |
| 7947 |
|
| 7948 |
Enabling KVM_X2APIC_API_USE_32BIT_IDS changes the behavior of |
| 7949 |
KVM_SET_GSI_ROUTING, KVM_SIGNAL_MSI, KVM_SET_LAPIC, and KVM_GET_LAPIC, |
| 7950 |
allowing the use of 32-bit APIC IDs. See KVM_CAP_X2APIC_API in their |
| 7951 |
respective sections. |
| 7952 |
|
| 7953 |
KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK must be enabled for x2APIC to work |
| 7954 |
in logical mode or with more than 255 VCPUs. Otherwise, KVM treats 0xff |
| 7955 |
as a broadcast even in x2APIC mode in order to support physical x2APIC |
| 7956 |
without interrupt remapping. This is undesirable in logical mode, |
| 7957 |
where 0xff represents CPUs 0-7 in cluster 0. |
| 7958 |
|
| 7959 |
Setting KVM_X2APIC_ENABLE_SUPPRESS_EOI_BROADCAST instructs KVM to enable |
| 7960 |
Suppress EOI Broadcasts. KVM will advertise support for Suppress EOI |
| 7961 |
Broadcast to the guest and suppress LAPIC EOI broadcasts when the guest |
| 7962 |
sets the Suppress EOI Broadcast bit in the SPIV register. This flag is |
| 7963 |
supported only when using a split IRQCHIP. |
| 7964 |
|
| 7965 |
Setting KVM_X2APIC_DISABLE_SUPPRESS_EOI_BROADCAST disables support for |
| 7966 |
Suppress EOI Broadcasts entirely, i.e. instructs KVM to NOT advertise |
| 7967 |
support to the guest. |
| 7968 |
|
| 7969 |
Modern VMMs should either enable KVM_X2APIC_ENABLE_SUPPRESS_EOI_BROADCAST |
| 7970 |
or KVM_X2APIC_DISABLE_SUPPRESS_EOI_BROADCAST. If not, legacy quirky |
| 7971 |
behavior will be used by KVM: in split IRQCHIP mode, KVM will advertise |
| 7972 |
support for Suppress EOI Broadcasts but not actually suppress EOI |
| 7973 |
broadcasts; for in-kernel IRQCHIP mode, KVM will not advertise support for |
| 7974 |
Suppress EOI Broadcasts. |
| 7975 |
|
| 7976 |
Setting both KVM_X2APIC_ENABLE_SUPPRESS_EOI_BROADCAST and |
| 7977 |
KVM_X2APIC_DISABLE_SUPPRESS_EOI_BROADCAST will fail with an EINVAL error, |
| 7978 |
as will setting KVM_X2APIC_ENABLE_SUPPRESS_EOI_BROADCAST without a split |
| 7979 |
IRCHIP. |
| 7980 |
|
| 7981 |
7.8 KVM_CAP_S390_USER_INSTR0 |
| 7982 |
---------------------------- |
| 7983 |
|
| 7984 |
:Architectures: s390 |
| 7985 |
:Parameters: none |
| 7986 |
|
| 7987 |
With this capability enabled, the illegal instruction 0x0000 (2 bytes) will |
| 7988 |
be intercepted and forwarded to user space. User space can use this |
| 7989 |
mechanism e.g. to realize 2-byte software breakpoints. The kernel will |
| 7990 |
not inject an operating exception for these instructions, user space has |
| 7991 |
to take care of that. |
| 7992 |
|
| 7993 |
This capability can be enabled dynamically even if VCPUs were already |
| 7994 |
created and are running. |
| 7995 |
|
| 7996 |
7.9 KVM_CAP_S390_GS |
| 7997 |
------------------- |
| 7998 |
|
| 7999 |
:Architectures: s390 |
| 8000 |
:Parameters: none |
| 8001 |
:Returns: 0 on success; -EINVAL if the machine does not support |
| 8002 |
guarded storage; -EBUSY if a VCPU has already been created. |
| 8003 |
|
| 8004 |
Allows use of guarded storage for the KVM guest. |
| 8005 |
|
| 8006 |
7.10 KVM_CAP_S390_AIS |
| 8007 |
--------------------- |
| 8008 |
|
| 8009 |
:Architectures: s390 |
| 8010 |
:Parameters: none |
| 8011 |
|
| 8012 |
Allow use of adapter-interruption suppression. |
| 8013 |
:Returns: 0 on success; -EBUSY if a VCPU has already been created. |
| 8014 |
|
| 8015 |
7.11 KVM_CAP_PPC_SMT |
| 8016 |
-------------------- |
| 8017 |
|
| 8018 |
:Architectures: ppc |
| 8019 |
:Parameters: vsmt_mode, flags |
| 8020 |
|
| 8021 |
Enabling this capability on a VM provides userspace with a way to set |
| 8022 |
the desired virtual SMT mode (i.e. the number of virtual CPUs per |
| 8023 |
virtual core). The virtual SMT mode, vsmt_mode, must be a power of 2 |
| 8024 |
between 1 and 8. On POWER8, vsmt_mode must also be no greater than |
| 8025 |
the number of threads per subcore for the host. Currently flags must |
| 8026 |
be 0. A successful call to enable this capability will result in |
| 8027 |
vsmt_mode being returned when the KVM_CAP_PPC_SMT capability is |
| 8028 |
subsequently queried for the VM. This capability is only supported by |
| 8029 |
HV KVM, and can only be set before any VCPUs have been created. |
| 8030 |
The KVM_CAP_PPC_SMT_POSSIBLE capability indicates which virtual SMT |
| 8031 |
modes are available. |
| 8032 |
|
| 8033 |
7.12 KVM_CAP_PPC_FWNMI |
| 8034 |
---------------------- |
| 8035 |
|
| 8036 |
:Architectures: ppc |
| 8037 |
:Parameters: none |
| 8038 |
|
| 8039 |
With this capability a machine check exception in the guest address |
| 8040 |
space will cause KVM to exit the guest with NMI exit reason. This |
| 8041 |
enables QEMU to build error log and branch to guest kernel registered |
| 8042 |
machine check handling routine. Without this capability KVM will |
| 8043 |
branch to guests' 0x200 interrupt vector. |
| 8044 |
|
| 8045 |
7.13 KVM_CAP_X86_DISABLE_EXITS |
| 8046 |
------------------------------ |
| 8047 |
|
| 8048 |
:Architectures: x86 |
| 8049 |
:Parameters: args[0] defines which exits are disabled |
| 8050 |
:Returns: 0 on success, -EINVAL when args[0] contains invalid exits |
| 8051 |
or if any vCPUs have already been created |
| 8052 |
|
| 8053 |
Valid bits in args[0] are:: |
| 8054 |
|
| 8055 |
#define KVM_X86_DISABLE_EXITS_MWAIT (1 << 0) |
| 8056 |
#define KVM_X86_DISABLE_EXITS_HLT (1 << 1) |
| 8057 |
#define KVM_X86_DISABLE_EXITS_PAUSE (1 << 2) |
| 8058 |
#define KVM_X86_DISABLE_EXITS_CSTATE (1 << 3) |
| 8059 |
#define KVM_X86_DISABLE_EXITS_APERFMPERF (1 << 4) |
| 8060 |
|
| 8061 |
Enabling this capability on a VM provides userspace with a way to no |
| 8062 |
longer intercept some instructions for improved latency in some |
| 8063 |
workloads, and is suggested when vCPUs are associated to dedicated |
| 8064 |
physical CPUs. More bits can be added in the future; userspace can |
| 8065 |
just pass the KVM_CHECK_EXTENSION result to KVM_ENABLE_CAP to disable |
| 8066 |
all such vmexits. |
| 8067 |
|
| 8068 |
Do not enable KVM_FEATURE_PV_UNHALT if you disable HLT exits. |
| 8069 |
|
| 8070 |
Virtualizing the ``IA32_APERF`` and ``IA32_MPERF`` MSRs requires more |
| 8071 |
than just disabling APERF/MPERF exits. While both Intel and AMD |
| 8072 |
document strict usage conditions for these MSRs--emphasizing that only |
| 8073 |
the ratio of their deltas over a time interval (T0 to T1) is |
| 8074 |
architecturally defined--simply passing through the MSRs can still |
| 8075 |
produce an incorrect ratio. |
| 8076 |
|
| 8077 |
This erroneous ratio can occur if, between T0 and T1: |
| 8078 |
|
| 8079 |
1. The vCPU thread migrates between logical processors. |
| 8080 |
2. Live migration or suspend/resume operations take place. |
| 8081 |
3. Another task shares the vCPU's logical processor. |
| 8082 |
4. C-states lower than C0 are emulated (e.g., via HLT interception). |
| 8083 |
5. The guest TSC frequency doesn't match the host TSC frequency. |
| 8084 |
|
| 8085 |
Due to these complexities, KVM does not automatically associate this |
| 8086 |
passthrough capability with the guest CPUID bit, |
| 8087 |
``CPUID.6:ECX.APERFMPERF[bit 0]``. Userspace VMMs that deem this |
| 8088 |
mechanism adequate for virtualizing the ``IA32_APERF`` and |
| 8089 |
``IA32_MPERF`` MSRs must set the guest CPUID bit explicitly. |
| 8090 |
|
| 8091 |
|
| 8092 |
7.14 KVM_CAP_S390_HPAGE_1M |
| 8093 |
-------------------------- |
| 8094 |
|
| 8095 |
:Architectures: s390 |
| 8096 |
:Parameters: none |
| 8097 |
:Returns: 0 on success, -EINVAL if hpage module parameter was not set |
| 8098 |
or cmma is enabled, or the VM has the KVM_VM_S390_UCONTROL |
| 8099 |
flag set |
| 8100 |
|
| 8101 |
With this capability the KVM support for memory backing with 1m pages |
| 8102 |
through hugetlbfs can be enabled for a VM. After the capability is |
| 8103 |
enabled, cmma can't be enabled anymore and pfmfi and the storage key |
| 8104 |
interpretation are disabled. If cmma has already been enabled or the |
| 8105 |
hpage module parameter is not set to 1, -EINVAL is returned. |
| 8106 |
|
| 8107 |
While it is generally possible to create a huge page backed VM without |
| 8108 |
this capability, the VM will not be able to run. |
| 8109 |
|
| 8110 |
7.15 KVM_CAP_MSR_PLATFORM_INFO |
| 8111 |
------------------------------ |
| 8112 |
|
| 8113 |
:Architectures: x86 |
| 8114 |
:Parameters: args[0] whether feature should be enabled or not |
| 8115 |
|
| 8116 |
With this capability, a guest may read the MSR_PLATFORM_INFO MSR. Otherwise, |
| 8117 |
a #GP would be raised when the guest tries to access. Currently, this |
| 8118 |
capability does not enable write permissions of this MSR for the guest. |
| 8119 |
|
| 8120 |
7.16 KVM_CAP_PPC_NESTED_HV |
| 8121 |
-------------------------- |
| 8122 |
|
| 8123 |
:Architectures: ppc |
| 8124 |
:Parameters: none |
| 8125 |
:Returns: 0 on success, -EINVAL when the implementation doesn't support |
| 8126 |
nested-HV virtualization. |
| 8127 |
|
| 8128 |
HV-KVM on POWER9 and later systems allows for "nested-HV" |
| 8129 |
virtualization, which provides a way for a guest VM to run guests that |
| 8130 |
can run using the CPU's supervisor mode (privileged non-hypervisor |
| 8131 |
state). Enabling this capability on a VM depends on the CPU having |
| 8132 |
the necessary functionality and on the facility being enabled with a |
| 8133 |
kvm-hv module parameter. |
| 8134 |
|
| 8135 |
7.17 KVM_CAP_EXCEPTION_PAYLOAD |
| 8136 |
------------------------------ |
| 8137 |
|
| 8138 |
:Architectures: x86 |
| 8139 |
:Parameters: args[0] whether feature should be enabled or not |
| 8140 |
|
| 8141 |
With this capability enabled, CR2 will not be modified prior to the |
| 8142 |
emulated VM-exit when L1 intercepts a #PF exception that occurs in |
| 8143 |
L2. Similarly, for kvm-intel only, DR6 will not be modified prior to |
| 8144 |
the emulated VM-exit when L1 intercepts a #DB exception that occurs in |
| 8145 |
L2. As a result, when KVM_GET_VCPU_EVENTS reports a pending #PF (or |
| 8146 |
#DB) exception for L2, exception.has_payload will be set and the |
| 8147 |
faulting address (or the new DR6 bits*) will be reported in the |
| 8148 |
exception_payload field. Similarly, when userspace injects a #PF (or |
| 8149 |
#DB) into L2 using KVM_SET_VCPU_EVENTS, it is expected to set |
| 8150 |
exception.has_payload and to put the faulting address - or the new DR6 |
| 8151 |
bits\ [#]_ - in the exception_payload field. |
| 8152 |
|
| 8153 |
This capability also enables exception.pending in struct |
| 8154 |
kvm_vcpu_events, which allows userspace to distinguish between pending |
| 8155 |
and injected exceptions. |
| 8156 |
|
| 8157 |
|
| 8158 |
.. [#] For the new DR6 bits, note that bit 16 is set iff the #DB exception |
| 8159 |
will clear DR6.RTM. |
| 8160 |
|
| 8161 |
7.18 KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 |
| 8162 |
-------------------------------------- |
| 8163 |
|
| 8164 |
:Architectures: x86, arm64, mips |
| 8165 |
:Parameters: args[0] whether feature should be enabled or not |
| 8166 |
|
| 8167 |
Valid flags are:: |
| 8168 |
|
| 8169 |
#define KVM_DIRTY_LOG_MANUAL_PROTECT_ENABLE (1 << 0) |
| 8170 |
#define KVM_DIRTY_LOG_INITIALLY_SET (1 << 1) |
| 8171 |
|
| 8172 |
With KVM_DIRTY_LOG_MANUAL_PROTECT_ENABLE is set, KVM_GET_DIRTY_LOG will not |
| 8173 |
automatically clear and write-protect all pages that are returned as dirty. |
| 8174 |
Rather, userspace will have to do this operation separately using |
| 8175 |
KVM_CLEAR_DIRTY_LOG. |
| 8176 |
|
| 8177 |
At the cost of a slightly more complicated operation, this provides better |
| 8178 |
scalability and responsiveness for two reasons. First, |
| 8179 |
KVM_CLEAR_DIRTY_LOG ioctl can operate on a 64-page granularity rather |
| 8180 |
than requiring to sync a full memslot; this ensures that KVM does not |
| 8181 |
take spinlocks for an extended period of time. Second, in some cases a |
| 8182 |
large amount of time can pass between a call to KVM_GET_DIRTY_LOG and |
| 8183 |
userspace actually using the data in the page. Pages can be modified |
| 8184 |
during this time, which is inefficient for both the guest and userspace: |
| 8185 |
the guest will incur a higher penalty due to write protection faults, |
| 8186 |
while userspace can see false reports of dirty pages. Manual reprotection |
| 8187 |
helps reducing this time, improving guest performance and reducing the |
| 8188 |
number of dirty log false positives. |
| 8189 |
|
| 8190 |
With KVM_DIRTY_LOG_INITIALLY_SET set, all the bits of the dirty bitmap |
| 8191 |
will be initialized to 1 when created. This also improves performance because |
| 8192 |
dirty logging can be enabled gradually in small chunks on the first call |
| 8193 |
to KVM_CLEAR_DIRTY_LOG. KVM_DIRTY_LOG_INITIALLY_SET depends on |
| 8194 |
KVM_DIRTY_LOG_MANUAL_PROTECT_ENABLE (it is also only available on |
| 8195 |
x86, arm64 and riscv for now). |
| 8196 |
|
| 8197 |
KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 was previously available under the name |
| 8198 |
KVM_CAP_MANUAL_DIRTY_LOG_PROTECT, but the implementation had bugs that make |
| 8199 |
it hard or impossible to use it correctly. The availability of |
| 8200 |
KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 signals that those bugs are fixed. |
| 8201 |
Userspace should not try to use KVM_CAP_MANUAL_DIRTY_LOG_PROTECT. |
| 8202 |
|
| 8203 |
7.19 KVM_CAP_PPC_SECURE_GUEST |
| 8204 |
------------------------------ |
| 8205 |
|
| 8206 |
:Architectures: ppc |
| 8207 |
|
| 8208 |
This capability indicates that KVM is running on a host that has |
| 8209 |
ultravisor firmware and thus can support a secure guest. On such a |
| 8210 |
system, a guest can ask the ultravisor to make it a secure guest, |
| 8211 |
one whose memory is inaccessible to the host except for pages which |
| 8212 |
are explicitly requested to be shared with the host. The ultravisor |
| 8213 |
notifies KVM when a guest requests to become a secure guest, and KVM |
| 8214 |
has the opportunity to veto the transition. |
| 8215 |
|
| 8216 |
If present, this capability can be enabled for a VM, meaning that KVM |
| 8217 |
will allow the transition to secure guest mode. Otherwise KVM will |
| 8218 |
veto the transition. |
| 8219 |
|
| 8220 |
7.20 KVM_CAP_HALT_POLL |
| 8221 |
---------------------- |
| 8222 |
|
| 8223 |
:Architectures: all |
| 8224 |
:Target: VM |
| 8225 |
:Parameters: args[0] is the maximum poll time in nanoseconds |
| 8226 |
:Returns: 0 on success; -1 on error |
| 8227 |
|
| 8228 |
KVM_CAP_HALT_POLL overrides the kvm.halt_poll_ns module parameter to set the |
| 8229 |
maximum halt-polling time for all vCPUs in the target VM. This capability can |
| 8230 |
be invoked at any time and any number of times to dynamically change the |
| 8231 |
maximum halt-polling time. |
| 8232 |
|
| 8233 |
See Documentation/virt/kvm/halt-polling.rst for more information on halt |
| 8234 |
polling. |
| 8235 |
|
| 8236 |
7.21 KVM_CAP_X86_USER_SPACE_MSR |
| 8237 |
------------------------------- |
| 8238 |
|
| 8239 |
:Architectures: x86 |
| 8240 |
:Target: VM |
| 8241 |
:Parameters: args[0] contains the mask of KVM_MSR_EXIT_REASON_* events to report |
| 8242 |
:Returns: 0 on success; -1 on error |
| 8243 |
|
| 8244 |
This capability allows userspace to intercept RDMSR and WRMSR instructions if |
| 8245 |
access to an MSR is denied. By default, KVM injects #GP on denied accesses. |
| 8246 |
|
| 8247 |
When a guest requests to read or write an MSR, KVM may not implement all MSRs |
| 8248 |
that are relevant to a respective system. It also does not differentiate by |
| 8249 |
CPU type. |
| 8250 |
|
| 8251 |
To allow more fine grained control over MSR handling, userspace may enable |
| 8252 |
this capability. With it enabled, MSR accesses that match the mask specified in |
| 8253 |
args[0] and would trigger a #GP inside the guest will instead trigger |
| 8254 |
KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR exit notifications. Userspace |
| 8255 |
can then implement model specific MSR handling and/or user notifications |
| 8256 |
to inform a user that an MSR was not emulated/virtualized by KVM. |
| 8257 |
|
| 8258 |
The valid mask flags are: |
| 8259 |
|
| 8260 |
============================ =============================================== |
| 8261 |
KVM_MSR_EXIT_REASON_UNKNOWN intercept accesses to unknown (to KVM) MSRs |
| 8262 |
KVM_MSR_EXIT_REASON_INVAL intercept accesses that are architecturally |
| 8263 |
invalid according to the vCPU model and/or mode |
| 8264 |
KVM_MSR_EXIT_REASON_FILTER intercept accesses that are denied by userspace |
| 8265 |
via KVM_X86_SET_MSR_FILTER |
| 8266 |
============================ =============================================== |
| 8267 |
|
| 8268 |
7.22 KVM_CAP_X86_BUS_LOCK_EXIT |
| 8269 |
------------------------------- |
| 8270 |
|
| 8271 |
:Architectures: x86 |
| 8272 |
:Target: VM |
| 8273 |
:Parameters: args[0] defines the policy used when bus locks detected in guest |
| 8274 |
:Returns: 0 on success, -EINVAL when args[0] contains invalid bits |
| 8275 |
|
| 8276 |
Valid bits in args[0] are:: |
| 8277 |
|
| 8278 |
#define KVM_BUS_LOCK_DETECTION_OFF (1 << 0) |
| 8279 |
#define KVM_BUS_LOCK_DETECTION_EXIT (1 << 1) |
| 8280 |
|
| 8281 |
Enabling this capability on a VM provides userspace with a way to select a |
| 8282 |
policy to handle the bus locks detected in guest. Userspace can obtain the |
| 8283 |
supported modes from the result of KVM_CHECK_EXTENSION and define it through |
| 8284 |
the KVM_ENABLE_CAP. The supported modes are mutually-exclusive. |
| 8285 |
|
| 8286 |
This capability allows userspace to force VM exits on bus locks detected in the |
| 8287 |
guest, irrespective whether or not the host has enabled split-lock detection |
| 8288 |
(which triggers an #AC exception that KVM intercepts). This capability is |
| 8289 |
intended to mitigate attacks where a malicious/buggy guest can exploit bus |
| 8290 |
locks to degrade the performance of the whole system. |
| 8291 |
|
| 8292 |
If KVM_BUS_LOCK_DETECTION_OFF is set, KVM doesn't force guest bus locks to VM |
| 8293 |
exit, although the host kernel's split-lock #AC detection still applies, if |
| 8294 |
enabled. |
| 8295 |
|
| 8296 |
If KVM_BUS_LOCK_DETECTION_EXIT is set, KVM enables a CPU feature that ensures |
| 8297 |
bus locks in the guest trigger a VM exit, and KVM exits to userspace for all |
| 8298 |
such VM exits, e.g. to allow userspace to throttle the offending guest and/or |
| 8299 |
apply some other policy-based mitigation. When exiting to userspace, KVM sets |
| 8300 |
KVM_RUN_X86_BUS_LOCK in vcpu-run->flags, and conditionally sets the exit_reason |
| 8301 |
to KVM_EXIT_X86_BUS_LOCK. |
| 8302 |
|
| 8303 |
Due to differences in the underlying hardware implementation, the vCPU's RIP at |
| 8304 |
the time of exit diverges between Intel and AMD. On Intel hosts, RIP points at |
| 8305 |
the next instruction, i.e. the exit is trap-like. On AMD hosts, RIP points at |
| 8306 |
the offending instruction, i.e. the exit is fault-like. |
| 8307 |
|
| 8308 |
Note! Detected bus locks may be coincident with other exits to userspace, i.e. |
| 8309 |
KVM_RUN_X86_BUS_LOCK should be checked regardless of the primary exit reason if |
| 8310 |
userspace wants to take action on all detected bus locks. |
| 8311 |
|
| 8312 |
7.23 KVM_CAP_PPC_DAWR1 |
| 8313 |
---------------------- |
| 8314 |
|
| 8315 |
:Architectures: ppc |
| 8316 |
:Parameters: none |
| 8317 |
:Returns: 0 on success, -EINVAL when CPU doesn't support 2nd DAWR |
| 8318 |
|
| 8319 |
This capability can be used to check / enable 2nd DAWR feature provided |
| 8320 |
by POWER10 processor. |
| 8321 |
|
| 8322 |
|
| 8323 |
7.24 KVM_CAP_VM_COPY_ENC_CONTEXT_FROM |
| 8324 |
------------------------------------- |
| 8325 |
|
| 8326 |
:Architectures: x86 SEV enabled |
| 8327 |
:Type: vm |
| 8328 |
:Parameters: args[0] is the fd of the source vm |
| 8329 |
:Returns: 0 on success; ENOTTY on error |
| 8330 |
|
| 8331 |
This capability enables userspace to copy encryption context from the vm |
| 8332 |
indicated by the fd to the vm this is called on. |
| 8333 |
|
| 8334 |
This is intended to support in-guest workloads scheduled by the host. This |
| 8335 |
allows the in-guest workload to maintain its own NPTs and keeps the two vms |
| 8336 |
from accidentally clobbering each other with interrupts and the like (separate |
| 8337 |
APIC/MSRs/etc). |
| 8338 |
|
| 8339 |
7.25 KVM_CAP_SGX_ATTRIBUTE |
| 8340 |
-------------------------- |
| 8341 |
|
| 8342 |
:Architectures: x86 |
| 8343 |
:Target: VM |
| 8344 |
:Parameters: args[0] is a file handle of a SGX attribute file in securityfs |
| 8345 |
:Returns: 0 on success, -EINVAL if the file handle is invalid or if a requested |
| 8346 |
attribute is not supported by KVM. |
| 8347 |
|
| 8348 |
KVM_CAP_SGX_ATTRIBUTE enables a userspace VMM to grant a VM access to one or |
| 8349 |
more privileged enclave attributes. args[0] must hold a file handle to a valid |
| 8350 |
SGX attribute file corresponding to an attribute that is supported/restricted |
| 8351 |
by KVM (currently only PROVISIONKEY). |
| 8352 |
|
| 8353 |
The SGX subsystem restricts access to a subset of enclave attributes to provide |
| 8354 |
additional security for an uncompromised kernel, e.g. use of the PROVISIONKEY |
| 8355 |
is restricted to deter malware from using the PROVISIONKEY to obtain a stable |
| 8356 |
system fingerprint. To prevent userspace from circumventing such restrictions |
| 8357 |
by running an enclave in a VM, KVM prevents access to privileged attributes by |
| 8358 |
default. |
| 8359 |
|
| 8360 |
See Documentation/arch/x86/sgx.rst for more details. |
| 8361 |
|
| 8362 |
7.27 KVM_CAP_EXIT_ON_EMULATION_FAILURE |
| 8363 |
-------------------------------------- |
| 8364 |
|
| 8365 |
:Architectures: x86 |
| 8366 |
:Parameters: args[0] whether the feature should be enabled or not |
| 8367 |
|
| 8368 |
When this capability is enabled, an emulation failure will result in an exit |
| 8369 |
to userspace with KVM_INTERNAL_ERROR (except when the emulator was invoked |
| 8370 |
to handle a VMware backdoor instruction). Furthermore, KVM will now provide up |
| 8371 |
to 15 instruction bytes for any exit to userspace resulting from an emulation |
| 8372 |
failure. When these exits to userspace occur use the emulation_failure struct |
| 8373 |
instead of the internal struct. They both have the same layout, but the |
| 8374 |
emulation_failure struct matches the content better. It also explicitly |
| 8375 |
defines the 'flags' field which is used to describe the fields in the struct |
| 8376 |
that are valid (ie: if KVM_INTERNAL_ERROR_EMULATION_FLAG_INSTRUCTION_BYTES is |
| 8377 |
set in the 'flags' field then both 'insn_size' and 'insn_bytes' have valid data |
| 8378 |
in them.) |
| 8379 |
|
| 8380 |
7.28 KVM_CAP_ARM_MTE |
| 8381 |
-------------------- |
| 8382 |
|
| 8383 |
:Architectures: arm64 |
| 8384 |
:Parameters: none |
| 8385 |
|
| 8386 |
This capability indicates that KVM (and the hardware) supports exposing the |
| 8387 |
Memory Tagging Extensions (MTE) to the guest. It must also be enabled by the |
| 8388 |
VMM before creating any VCPUs to allow the guest access. Note that MTE is only |
| 8389 |
available to a guest running in AArch64 mode and enabling this capability will |
| 8390 |
cause attempts to create AArch32 VCPUs to fail. |
| 8391 |
|
| 8392 |
When enabled the guest is able to access tags associated with any memory given |
| 8393 |
to the guest. KVM will ensure that the tags are maintained during swap or |
| 8394 |
hibernation of the host; however the VMM needs to manually save/restore the |
| 8395 |
tags as appropriate if the VM is migrated. |
| 8396 |
|
| 8397 |
When this capability is enabled all memory in memslots must be mapped as |
| 8398 |
``MAP_ANONYMOUS`` or with a RAM-based file mapping (``tmpfs``, ``memfd``), |
| 8399 |
attempts to create a memslot with an invalid mmap will result in an |
| 8400 |
-EINVAL return. |
| 8401 |
|
| 8402 |
When enabled the VMM may make use of the ``KVM_ARM_MTE_COPY_TAGS`` ioctl to |
| 8403 |
perform a bulk copy of tags to/from the guest. |
| 8404 |
|
| 8405 |
7.29 KVM_CAP_VM_MOVE_ENC_CONTEXT_FROM |
| 8406 |
------------------------------------- |
| 8407 |
|
| 8408 |
:Architectures: x86 SEV enabled |
| 8409 |
:Type: vm |
| 8410 |
:Parameters: args[0] is the fd of the source vm |
| 8411 |
:Returns: 0 on success |
| 8412 |
|
| 8413 |
This capability enables userspace to migrate the encryption context from the VM |
| 8414 |
indicated by the fd to the VM this is called on. |
| 8415 |
|
| 8416 |
This is intended to support intra-host migration of VMs between userspace VMMs, |
| 8417 |
upgrading the VMM process without interrupting the guest. |
| 8418 |
|
| 8419 |
7.31 KVM_CAP_DISABLE_QUIRKS2 |
| 8420 |
---------------------------- |
| 8421 |
|
| 8422 |
:Parameters: args[0] - set of KVM quirks to disable |
| 8423 |
:Architectures: x86 |
| 8424 |
:Type: vm |
| 8425 |
|
| 8426 |
This capability, if enabled, will cause KVM to disable some behavior |
| 8427 |
quirks. |
| 8428 |
|
| 8429 |
Calling KVM_CHECK_EXTENSION for this capability returns a bitmask of |
| 8430 |
quirks that can be disabled in KVM. |
| 8431 |
|
| 8432 |
The argument to KVM_ENABLE_CAP for this capability is a bitmask of |
| 8433 |
quirks to disable, and must be a subset of the bitmask returned by |
| 8434 |
KVM_CHECK_EXTENSION. |
| 8435 |
|
| 8436 |
The valid bits in cap.args[0] are: |
| 8437 |
|
| 8438 |
======================================== ================================================ |
| 8439 |
KVM_X86_QUIRK_LINT0_REENABLED By default, the reset value for the LVT |
| 8440 |
LINT0 register is 0x700 (APIC_MODE_EXTINT). |
| 8441 |
When this quirk is disabled, the reset value |
| 8442 |
is 0x10000 (APIC_LVT_MASKED). |
| 8443 |
|
| 8444 |
KVM_X86_QUIRK_CD_NW_CLEARED By default, KVM clears CR0.CD and CR0.NW on |
| 8445 |
AMD CPUs to workaround buggy guest firmware |
| 8446 |
that runs in perpetuity with CR0.CD, i.e. |
| 8447 |
with caches in "no fill" mode. |
| 8448 |
|
| 8449 |
When this quirk is disabled, KVM does not |
| 8450 |
change the value of CR0.CD and CR0.NW. |
| 8451 |
|
| 8452 |
KVM_X86_QUIRK_LAPIC_MMIO_HOLE By default, the MMIO LAPIC interface is |
| 8453 |
available even when configured for x2APIC |
| 8454 |
mode. When this quirk is disabled, KVM |
| 8455 |
disables the MMIO LAPIC interface if the |
| 8456 |
LAPIC is in x2APIC mode. |
| 8457 |
|
| 8458 |
KVM_X86_QUIRK_OUT_7E_INC_RIP By default, KVM pre-increments %rip before |
| 8459 |
exiting to userspace for an OUT instruction |
| 8460 |
to port 0x7e. When this quirk is disabled, |
| 8461 |
KVM does not pre-increment %rip before |
| 8462 |
exiting to userspace. |
| 8463 |
|
| 8464 |
KVM_X86_QUIRK_MISC_ENABLE_NO_MWAIT When this quirk is disabled, KVM sets |
| 8465 |
CPUID.01H:ECX[bit 3] (MONITOR/MWAIT) if |
| 8466 |
IA32_MISC_ENABLE[bit 18] (MWAIT) is set. |
| 8467 |
Additionally, when this quirk is disabled, |
| 8468 |
KVM clears CPUID.01H:ECX[bit 3] if |
| 8469 |
IA32_MISC_ENABLE[bit 18] is cleared. |
| 8470 |
|
| 8471 |
KVM_X86_QUIRK_FIX_HYPERCALL_INSN By default, KVM rewrites guest |
| 8472 |
VMMCALL/VMCALL instructions to match the |
| 8473 |
vendor's hypercall instruction for the |
| 8474 |
system. When this quirk is disabled, KVM |
| 8475 |
will no longer rewrite invalid guest |
| 8476 |
hypercall instructions. Executing the |
| 8477 |
incorrect hypercall instruction will |
| 8478 |
generate a #UD within the guest. |
| 8479 |
|
| 8480 |
KVM_X86_QUIRK_MWAIT_NEVER_UD_FAULTS By default, KVM emulates MONITOR/MWAIT (if |
| 8481 |
they are intercepted) as NOPs regardless of |
| 8482 |
whether or not MONITOR/MWAIT are supported |
| 8483 |
according to guest CPUID. When this quirk |
| 8484 |
is disabled and KVM_X86_DISABLE_EXITS_MWAIT |
| 8485 |
is not set (MONITOR/MWAIT are intercepted), |
| 8486 |
KVM will inject a #UD on MONITOR/MWAIT if |
| 8487 |
they're unsupported per guest CPUID. Note, |
| 8488 |
KVM will modify MONITOR/MWAIT support in |
| 8489 |
guest CPUID on writes to MISC_ENABLE if |
| 8490 |
KVM_X86_QUIRK_MISC_ENABLE_NO_MWAIT is |
| 8491 |
disabled. |
| 8492 |
|
| 8493 |
KVM_X86_QUIRK_SLOT_ZAP_ALL By default, for KVM_X86_DEFAULT_VM VMs, KVM |
| 8494 |
invalidates all SPTEs in all memslots and |
| 8495 |
address spaces when a memslot is deleted or |
| 8496 |
moved. When this quirk is disabled (or the |
| 8497 |
VM type isn't KVM_X86_DEFAULT_VM), KVM only |
| 8498 |
ensures the backing memory of the deleted |
| 8499 |
or moved memslot isn't reachable, i.e KVM |
| 8500 |
_may_ invalidate only SPTEs related to the |
| 8501 |
memslot. |
| 8502 |
|
| 8503 |
KVM_X86_QUIRK_STUFF_FEATURE_MSRS By default, at vCPU creation, KVM sets the |
| 8504 |
vCPU's MSR_IA32_PERF_CAPABILITIES (0x345), |
| 8505 |
MSR_IA32_ARCH_CAPABILITIES (0x10a), |
| 8506 |
MSR_PLATFORM_INFO (0xce), and all VMX MSRs |
| 8507 |
(0x480..0x492) to the maximal capabilities |
| 8508 |
supported by KVM. KVM also sets |
| 8509 |
MSR_IA32_UCODE_REV (0x8b) to an arbitrary |
| 8510 |
value (which is different for Intel vs. |
| 8511 |
AMD). Lastly, when guest CPUID is set (by |
| 8512 |
userspace), KVM modifies select VMX MSR |
| 8513 |
fields to force consistency between guest |
| 8514 |
CPUID and L2's effective ISA. When this |
| 8515 |
quirk is disabled, KVM zeroes the vCPU's MSR |
| 8516 |
values (with two exceptions, see below), |
| 8517 |
i.e. treats the feature MSRs like CPUID |
| 8518 |
leaves and gives userspace full control of |
| 8519 |
the vCPU model definition. This quirk does |
| 8520 |
not affect VMX MSRs CR0/CR4_FIXED1 (0x487 |
| 8521 |
and 0x489), as KVM does now allow them to |
| 8522 |
be set by userspace (KVM sets them based on |
| 8523 |
guest CPUID, for safety purposes). |
| 8524 |
|
| 8525 |
KVM_X86_QUIRK_IGNORE_GUEST_PAT By default, on Intel platforms, KVM ignores |
| 8526 |
guest PAT and forces the effective memory |
| 8527 |
type to WB in EPT. The quirk is not available |
| 8528 |
on Intel platforms which are incapable of |
| 8529 |
safely honoring guest PAT (i.e., without CPU |
| 8530 |
self-snoop, KVM always ignores guest PAT and |
| 8531 |
forces effective memory type to WB). It is |
| 8532 |
also ignored on AMD platforms or, on Intel, |
| 8533 |
when a VM has non-coherent DMA devices |
| 8534 |
assigned; KVM always honors guest PAT in |
| 8535 |
such case. The quirk is needed to avoid |
| 8536 |
slowdowns on certain Intel Xeon platforms |
| 8537 |
(e.g. ICX, SPR) where self-snoop feature is |
| 8538 |
supported but UC is slow enough to cause |
| 8539 |
issues with some older guests that use |
| 8540 |
UC instead of WC to map the video RAM. |
| 8541 |
Userspace can disable the quirk to honor |
| 8542 |
guest PAT if it knows that there is no such |
| 8543 |
guest software, for example if it does not |
| 8544 |
expose a bochs graphics device (which is |
| 8545 |
known to have had a buggy driver). |
| 8546 |
|
| 8547 |
KVM_X86_QUIRK_VMCS12_ALLOW_FREEZE_IN_SMM By default, KVM relaxes the consistency |
| 8548 |
check for GUEST_IA32_DEBUGCTL in vmcs12 |
| 8549 |
to allow FREEZE_IN_SMM to be set. When |
| 8550 |
this quirk is disabled, KVM requires this |
| 8551 |
bit to be cleared. Note that the vmcs02 |
| 8552 |
bit is still completely controlled by the |
| 8553 |
host, regardless of the quirk setting. |
| 8554 |
======================================== ================================================ |
| 8555 |
|
| 8556 |
7.32 KVM_CAP_MAX_VCPU_ID |
| 8557 |
------------------------ |
| 8558 |
|
| 8559 |
:Architectures: x86 |
| 8560 |
:Target: VM |
| 8561 |
:Parameters: args[0] - maximum APIC ID value set for current VM |
| 8562 |
:Returns: 0 on success, -EINVAL if args[0] is beyond KVM_MAX_VCPU_IDS |
| 8563 |
supported in KVM or if it has been set. |
| 8564 |
|
| 8565 |
This capability allows userspace to specify maximum possible APIC ID |
| 8566 |
assigned for current VM session prior to the creation of vCPUs, saving |
| 8567 |
memory for data structures indexed by the APIC ID. Userspace is able |
| 8568 |
to calculate the limit to APIC ID values from designated |
| 8569 |
CPU topology. |
| 8570 |
|
| 8571 |
The value can be changed only until KVM_ENABLE_CAP is set to a nonzero |
| 8572 |
value or until a vCPU is created. Upon creation of the first vCPU, |
| 8573 |
if the value was set to zero or KVM_ENABLE_CAP was not invoked, KVM |
| 8574 |
uses the return value of KVM_CHECK_EXTENSION(KVM_CAP_MAX_VCPU_ID) as |
| 8575 |
the maximum APIC ID. |
| 8576 |
|
| 8577 |
7.33 KVM_CAP_X86_NOTIFY_VMEXIT |
| 8578 |
------------------------------ |
| 8579 |
|
| 8580 |
:Architectures: x86 |
| 8581 |
:Target: VM |
| 8582 |
:Parameters: args[0] is the value of notify window as well as some flags |
| 8583 |
:Returns: 0 on success, -EINVAL if args[0] contains invalid flags or notify |
| 8584 |
VM exit is unsupported. |
| 8585 |
|
| 8586 |
Bits 63:32 of args[0] are used for notify window. |
| 8587 |
Bits 31:0 of args[0] are for some flags. Valid bits are:: |
| 8588 |
|
| 8589 |
#define KVM_X86_NOTIFY_VMEXIT_ENABLED (1 << 0) |
| 8590 |
#define KVM_X86_NOTIFY_VMEXIT_USER (1 << 1) |
| 8591 |
|
| 8592 |
This capability allows userspace to configure the notify VM exit on/off |
| 8593 |
in per-VM scope during VM creation. Notify VM exit is disabled by default. |
| 8594 |
When userspace sets KVM_X86_NOTIFY_VMEXIT_ENABLED bit in args[0], VMM will |
| 8595 |
enable this feature with the notify window provided, which will generate |
| 8596 |
a VM exit if no event window occurs in VM non-root mode for a specified of |
| 8597 |
time (notify window). |
| 8598 |
|
| 8599 |
If KVM_X86_NOTIFY_VMEXIT_USER is set in args[0], upon notify VM exits happen, |
| 8600 |
KVM would exit to userspace for handling. |
| 8601 |
|
| 8602 |
This capability is aimed to mitigate the threat that malicious VMs can |
| 8603 |
cause CPU stuck (due to event windows don't open up) and make the CPU |
| 8604 |
unavailable to host or other VMs. |
| 8605 |
|
| 8606 |
7.35 KVM_CAP_X86_APIC_BUS_CYCLES_NS |
| 8607 |
----------------------------------- |
| 8608 |
|
| 8609 |
:Architectures: x86 |
| 8610 |
:Target: VM |
| 8611 |
:Parameters: args[0] is the desired APIC bus clock rate, in nanoseconds |
| 8612 |
:Returns: 0 on success, -EINVAL if args[0] contains an invalid value for the |
| 8613 |
frequency or if any vCPUs have been created, -ENXIO if a virtual |
| 8614 |
local APIC has not been created using KVM_CREATE_IRQCHIP. |
| 8615 |
|
| 8616 |
This capability sets the VM's APIC bus clock frequency, used by KVM's in-kernel |
| 8617 |
virtual APIC when emulating APIC timers. KVM's default value can be retrieved |
| 8618 |
by KVM_CHECK_EXTENSION. |
| 8619 |
|
| 8620 |
Note: Userspace is responsible for correctly configuring CPUID 0x15, a.k.a. the |
| 8621 |
core crystal clock frequency, if a non-zero CPUID 0x15 is exposed to the guest. |
| 8622 |
|
| 8623 |
7.36 KVM_CAP_DIRTY_LOG_RING/KVM_CAP_DIRTY_LOG_RING_ACQ_REL |
| 8624 |
---------------------------------------------------------- |
| 8625 |
|
| 8626 |
:Architectures: x86, arm64, riscv |
| 8627 |
:Type: vm |
| 8628 |
:Parameters: args[0] - size of the dirty log ring |
| 8629 |
|
| 8630 |
KVM is capable of tracking dirty memory using ring buffers that are |
| 8631 |
mmapped into userspace; there is one dirty ring per vcpu. |
| 8632 |
|
| 8633 |
The dirty ring is available to userspace as an array of |
| 8634 |
``struct kvm_dirty_gfn``. Each dirty entry is defined as:: |
| 8635 |
|
| 8636 |
struct kvm_dirty_gfn { |
| 8637 |
__u32 flags; |
| 8638 |
__u32 slot; /* as_id | slot_id */ |
| 8639 |
__u64 offset; |
| 8640 |
}; |
| 8641 |
|
| 8642 |
The following values are defined for the flags field to define the |
| 8643 |
current state of the entry:: |
| 8644 |
|
| 8645 |
#define KVM_DIRTY_GFN_F_DIRTY BIT(0) |
| 8646 |
#define KVM_DIRTY_GFN_F_RESET BIT(1) |
| 8647 |
#define KVM_DIRTY_GFN_F_MASK 0x3 |
| 8648 |
|
| 8649 |
Userspace should call KVM_ENABLE_CAP ioctl right after KVM_CREATE_VM |
| 8650 |
ioctl to enable this capability for the new guest and set the size of |
| 8651 |
the rings. Enabling the capability is only allowed before creating any |
| 8652 |
vCPU, and the size of the ring must be a power of two. The larger the |
| 8653 |
ring buffer, the less likely the ring is full and the VM is forced to |
| 8654 |
exit to userspace. The optimal size depends on the workload, but it is |
| 8655 |
recommended that it be at least 64 KiB (4096 entries). |
| 8656 |
|
| 8657 |
Just like for dirty page bitmaps, the buffer tracks writes to |
| 8658 |
all user memory regions for which the KVM_MEM_LOG_DIRTY_PAGES flag was |
| 8659 |
set in KVM_SET_USER_MEMORY_REGION. Once a memory region is registered |
| 8660 |
with the flag set, userspace can start harvesting dirty pages from the |
| 8661 |
ring buffer. |
| 8662 |
|
| 8663 |
An entry in the ring buffer can be unused (flag bits ``00``), |
| 8664 |
dirty (flag bits ``01``) or harvested (flag bits ``1X``). The |
| 8665 |
state machine for the entry is as follows:: |
| 8666 |
|
| 8667 |
dirtied harvested reset |
| 8668 |
00 -----------> 01 -------------> 1X -------+ |
| 8669 |
^ | |
| 8670 |
| | |
| 8671 |
+------------------------------------------+ |
| 8672 |
|
| 8673 |
To harvest the dirty pages, userspace accesses the mmapped ring buffer |
| 8674 |
to read the dirty GFNs. If the flags has the DIRTY bit set (at this stage |
| 8675 |
the RESET bit must be cleared), then it means this GFN is a dirty GFN. |
| 8676 |
The userspace should harvest this GFN and mark the flags from state |
| 8677 |
``01b`` to ``1Xb`` (bit 0 will be ignored by KVM, but bit 1 must be set |
| 8678 |
to show that this GFN is harvested and waiting for a reset), and move |
| 8679 |
on to the next GFN. The userspace should continue to do this until the |
| 8680 |
flags of a GFN have the DIRTY bit cleared, meaning that it has harvested |
| 8681 |
all the dirty GFNs that were available. |
| 8682 |
|
| 8683 |
Note that on weakly ordered architectures, userspace accesses to the |
| 8684 |
ring buffer (and more specifically the 'flags' field) must be ordered, |
| 8685 |
using load-acquire/store-release accessors when available, or any |
| 8686 |
other memory barrier that will ensure this ordering. |
| 8687 |
|
| 8688 |
It's not necessary for userspace to harvest the all dirty GFNs at once. |
| 8689 |
However it must collect the dirty GFNs in sequence, i.e., the userspace |
| 8690 |
program cannot skip one dirty GFN to collect the one next to it. |
| 8691 |
|
| 8692 |
After processing one or more entries in the ring buffer, userspace |
| 8693 |
calls the VM ioctl KVM_RESET_DIRTY_RINGS to notify the kernel about |
| 8694 |
it, so that the kernel will reprotect those collected GFNs. |
| 8695 |
Therefore, the ioctl must be called *before* reading the content of |
| 8696 |
the dirty pages. |
| 8697 |
|
| 8698 |
The dirty ring can get full. When it happens, the KVM_RUN of the |
| 8699 |
vcpu will return with exit reason KVM_EXIT_DIRTY_RING_FULL. |
| 8700 |
|
| 8701 |
The dirty ring interface has a major difference comparing to the |
| 8702 |
KVM_GET_DIRTY_LOG interface in that, when reading the dirty ring from |
| 8703 |
userspace, it's still possible that the kernel has not yet flushed the |
| 8704 |
processor's dirty page buffers into the kernel buffer (with dirty bitmaps, the |
| 8705 |
flushing is done by the KVM_GET_DIRTY_LOG ioctl). To achieve that, one |
| 8706 |
needs to kick the vcpu out of KVM_RUN using a signal. The resulting |
| 8707 |
vmexit ensures that all dirty GFNs are flushed to the dirty rings. |
| 8708 |
|
| 8709 |
NOTE: KVM_CAP_DIRTY_LOG_RING_ACQ_REL is the only capability that |
| 8710 |
should be exposed by weakly ordered architecture, in order to indicate |
| 8711 |
the additional memory ordering requirements imposed on userspace when |
| 8712 |
reading the state of an entry and mutating it from DIRTY to HARVESTED. |
| 8713 |
Architecture with TSO-like ordering (such as x86) are allowed to |
| 8714 |
expose both KVM_CAP_DIRTY_LOG_RING and KVM_CAP_DIRTY_LOG_RING_ACQ_REL |
| 8715 |
to userspace. |
| 8716 |
|
| 8717 |
After enabling the dirty rings, the userspace needs to detect the |
| 8718 |
capability of KVM_CAP_DIRTY_LOG_RING_WITH_BITMAP to see whether the |
| 8719 |
ring structures can be backed by per-slot bitmaps. With this capability |
| 8720 |
advertised, it means the architecture can dirty guest pages without |
| 8721 |
vcpu/ring context, so that some of the dirty information will still be |
| 8722 |
maintained in the bitmap structure. KVM_CAP_DIRTY_LOG_RING_WITH_BITMAP |
| 8723 |
can't be enabled if the capability of KVM_CAP_DIRTY_LOG_RING_ACQ_REL |
| 8724 |
hasn't been enabled, or any memslot has been existing. |
| 8725 |
|
| 8726 |
Note that the bitmap here is only a backup of the ring structure. The |
| 8727 |
use of the ring and bitmap combination is only beneficial if there is |
| 8728 |
only a very small amount of memory that is dirtied out of vcpu/ring |
| 8729 |
context. Otherwise, the stand-alone per-slot bitmap mechanism needs to |
| 8730 |
be considered. |
| 8731 |
|
| 8732 |
To collect dirty bits in the backup bitmap, userspace can use the same |
| 8733 |
KVM_GET_DIRTY_LOG ioctl. KVM_CLEAR_DIRTY_LOG isn't needed as long as all |
| 8734 |
the generation of the dirty bits is done in a single pass. Collecting |
| 8735 |
the dirty bitmap should be the very last thing that the VMM does before |
| 8736 |
considering the state as complete. VMM needs to ensure that the dirty |
| 8737 |
state is final and avoid missing dirty pages from another ioctl ordered |
| 8738 |
after the bitmap collection. |
| 8739 |
|
| 8740 |
NOTE: Multiple examples of using the backup bitmap: (1) save vgic/its |
| 8741 |
tables through command KVM_DEV_ARM_{VGIC_GRP_CTRL, ITS_SAVE_TABLES} on |
| 8742 |
KVM device "kvm-arm-vgic-its". (2) restore vgic/its tables through |
| 8743 |
command KVM_DEV_ARM_{VGIC_GRP_CTRL, ITS_RESTORE_TABLES} on KVM device |
| 8744 |
"kvm-arm-vgic-its". VGICv3 LPI pending status is restored. (3) save |
| 8745 |
vgic3 pending table through KVM_DEV_ARM_VGIC_{GRP_CTRL, SAVE_PENDING_TABLES} |
| 8746 |
command on KVM device "kvm-arm-vgic-v3". |
| 8747 |
|
| 8748 |
7.37 KVM_CAP_PMU_CAPABILITY |
| 8749 |
--------------------------- |
| 8750 |
|
| 8751 |
:Architectures: x86 |
| 8752 |
:Type: vm |
| 8753 |
:Parameters: arg[0] is bitmask of PMU virtualization capabilities. |
| 8754 |
:Returns: 0 on success, -EINVAL when arg[0] contains invalid bits |
| 8755 |
|
| 8756 |
This capability alters PMU virtualization in KVM. |
| 8757 |
|
| 8758 |
Calling KVM_CHECK_EXTENSION for this capability returns a bitmask of |
| 8759 |
PMU virtualization capabilities that can be adjusted on a VM. |
| 8760 |
|
| 8761 |
The argument to KVM_ENABLE_CAP is also a bitmask and selects specific |
| 8762 |
PMU virtualization capabilities to be applied to the VM. This can |
| 8763 |
only be invoked on a VM prior to the creation of VCPUs. |
| 8764 |
|
| 8765 |
At this time, KVM_PMU_CAP_DISABLE is the only capability. Setting |
| 8766 |
this capability will disable PMU virtualization for that VM. Usermode |
| 8767 |
should adjust CPUID leaf 0xA to reflect that the PMU is disabled. |
| 8768 |
|
| 8769 |
7.38 KVM_CAP_VM_DISABLE_NX_HUGE_PAGES |
| 8770 |
------------------------------------- |
| 8771 |
|
| 8772 |
:Architectures: x86 |
| 8773 |
:Type: vm |
| 8774 |
:Parameters: arg[0] must be 0. |
| 8775 |
:Returns: 0 on success, -EPERM if the userspace process does not |
| 8776 |
have CAP_SYS_BOOT, -EINVAL if args[0] is not 0 or any vCPUs have been |
| 8777 |
created. |
| 8778 |
|
| 8779 |
This capability disables the NX huge pages mitigation for iTLB MULTIHIT. |
| 8780 |
|
| 8781 |
The capability has no effect if the nx_huge_pages module parameter is not set. |
| 8782 |
|
| 8783 |
This capability may only be set before any vCPUs are created. |
| 8784 |
|
| 8785 |
7.39 KVM_CAP_ARM_EAGER_SPLIT_CHUNK_SIZE |
| 8786 |
--------------------------------------- |
| 8787 |
|
| 8788 |
:Architectures: arm64 |
| 8789 |
:Type: vm |
| 8790 |
:Parameters: arg[0] is the new split chunk size. |
| 8791 |
:Returns: 0 on success, -EINVAL if any memslot was already created. |
| 8792 |
|
| 8793 |
This capability sets the chunk size used in Eager Page Splitting. |
| 8794 |
|
| 8795 |
Eager Page Splitting improves the performance of dirty-logging (used |
| 8796 |
in live migrations) when guest memory is backed by huge-pages. It |
| 8797 |
avoids splitting huge-pages (into PAGE_SIZE pages) on fault, by doing |
| 8798 |
it eagerly when enabling dirty logging (with the |
| 8799 |
KVM_MEM_LOG_DIRTY_PAGES flag for a memory region), or when using |
| 8800 |
KVM_CLEAR_DIRTY_LOG. |
| 8801 |
|
| 8802 |
The chunk size specifies how many pages to break at a time, using a |
| 8803 |
single allocation for each chunk. Bigger the chunk size, more pages |
| 8804 |
need to be allocated ahead of time. |
| 8805 |
|
| 8806 |
The chunk size needs to be a valid block size. The list of acceptable |
| 8807 |
block sizes is exposed in KVM_CAP_ARM_SUPPORTED_BLOCK_SIZES as a |
| 8808 |
64-bit bitmap (each bit describing a block size). The default value is |
| 8809 |
0, to disable the eager page splitting. |
| 8810 |
|
| 8811 |
7.40 KVM_CAP_EXIT_HYPERCALL |
| 8812 |
--------------------------- |
| 8813 |
|
| 8814 |
:Architectures: x86 |
| 8815 |
:Type: vm |
| 8816 |
|
| 8817 |
This capability, if enabled, will cause KVM to exit to userspace |
| 8818 |
with KVM_EXIT_HYPERCALL exit reason to process some hypercalls. |
| 8819 |
|
| 8820 |
Calling KVM_CHECK_EXTENSION for this capability will return a bitmask |
| 8821 |
of hypercalls that can be configured to exit to userspace. |
| 8822 |
Right now, the only such hypercall is KVM_HC_MAP_GPA_RANGE. |
| 8823 |
|
| 8824 |
The argument to KVM_ENABLE_CAP is also a bitmask, and must be a subset |
| 8825 |
of the result of KVM_CHECK_EXTENSION. KVM will forward to userspace |
| 8826 |
the hypercalls whose corresponding bit is in the argument, and return |
| 8827 |
ENOSYS for the others. |
| 8828 |
|
| 8829 |
7.41 KVM_CAP_ARM_SYSTEM_SUSPEND |
| 8830 |
------------------------------- |
| 8831 |
|
| 8832 |
:Architectures: arm64 |
| 8833 |
:Type: vm |
| 8834 |
|
| 8835 |
When enabled, KVM will exit to userspace with KVM_EXIT_SYSTEM_EVENT of |
| 8836 |
type KVM_SYSTEM_EVENT_SUSPEND to process the guest suspend request. |
| 8837 |
|
| 8838 |
7.42 KVM_CAP_ARM_WRITABLE_IMP_ID_REGS |
| 8839 |
------------------------------------- |
| 8840 |
|
| 8841 |
:Architectures: arm64 |
| 8842 |
:Target: VM |
| 8843 |
:Parameters: None |
| 8844 |
:Returns: 0 on success, -EINVAL if vCPUs have been created before enabling this |
| 8845 |
capability. |
| 8846 |
|
| 8847 |
This capability changes the behavior of the registers that identify a PE |
| 8848 |
implementation of the Arm architecture: MIDR_EL1, REVIDR_EL1, and AIDR_EL1. |
| 8849 |
By default, these registers are visible to userspace but treated as invariant. |
| 8850 |
|
| 8851 |
When this capability is enabled, KVM allows userspace to change the |
| 8852 |
aforementioned registers before the first KVM_RUN. These registers are VM |
| 8853 |
scoped, meaning that the same set of values are presented on all vCPUs in a |
| 8854 |
given VM. |
| 8855 |
|
| 8856 |
7.43 KVM_CAP_RISCV_MP_STATE_RESET |
| 8857 |
--------------------------------- |
| 8858 |
|
| 8859 |
:Architectures: riscv |
| 8860 |
:Type: VM |
| 8861 |
:Parameters: None |
| 8862 |
:Returns: 0 on success, -EINVAL if arg[0] is not zero |
| 8863 |
|
| 8864 |
When this capability is enabled, KVM resets the VCPU when setting |
| 8865 |
MP_STATE_INIT_RECEIVED through IOCTL. The original MP_STATE is preserved. |
| 8866 |
|
| 8867 |
7.44 KVM_CAP_ARM_CACHEABLE_PFNMAP_SUPPORTED |
| 8868 |
------------------------------------------- |
| 8869 |
|
| 8870 |
:Architectures: arm64 |
| 8871 |
:Target: VM |
| 8872 |
:Parameters: None |
| 8873 |
|
| 8874 |
This capability indicate to the userspace whether a PFNMAP memory region |
| 8875 |
can be safely mapped as cacheable. This relies on the presence of |
| 8876 |
force write back (FWB) feature support on the hardware. |
| 8877 |
|
| 8878 |
7.45 KVM_CAP_ARM_SEA_TO_USER |
| 8879 |
---------------------------- |
| 8880 |
|
| 8881 |
:Architecture: arm64 |
| 8882 |
:Target: VM |
| 8883 |
:Parameters: none |
| 8884 |
:Returns: 0 on success, -EINVAL if unsupported. |
| 8885 |
|
| 8886 |
When this capability is enabled, KVM may exit to userspace for SEAs taken to |
| 8887 |
EL2 resulting from a guest access. See ``KVM_EXIT_ARM_SEA`` for more |
| 8888 |
information. |
| 8889 |
|
| 8890 |
7.46 KVM_CAP_S390_USER_OPEREXEC |
| 8891 |
------------------------------- |
| 8892 |
|
| 8893 |
:Architectures: s390 |
| 8894 |
:Parameters: none |
| 8895 |
|
| 8896 |
When this capability is enabled KVM forwards all operation exceptions |
| 8897 |
that it doesn't handle itself to user space. This also includes the |
| 8898 |
0x0000 instructions managed by KVM_CAP_S390_USER_INSTR0. This is |
| 8899 |
helpful if user space wants to emulate instructions which are not |
| 8900 |
(yet) implemented in hardware. |
| 8901 |
|
| 8902 |
This capability can be enabled dynamically even if VCPUs were already |
| 8903 |
created and are running. |
| 8904 |
|
| 8905 |
8. Other capabilities. |
| 8906 |
====================== |
| 8907 |
|
| 8908 |
This section lists capabilities that give information about other |
| 8909 |
features of the KVM implementation. |
| 8910 |
|
| 8911 |
8.1 KVM_CAP_PPC_HWRNG |
| 8912 |
--------------------- |
| 8913 |
|
| 8914 |
:Architectures: ppc |
| 8915 |
|
| 8916 |
This capability, if KVM_CHECK_EXTENSION indicates that it is |
| 8917 |
available, means that the kernel has an implementation of the |
| 8918 |
H_RANDOM hypercall backed by a hardware random-number generator. |
| 8919 |
If present, the kernel H_RANDOM handler can be enabled for guest use |
| 8920 |
with the KVM_CAP_PPC_ENABLE_HCALL capability. |
| 8921 |
|
| 8922 |
8.3 KVM_CAP_PPC_MMU_RADIX |
| 8923 |
------------------------- |
| 8924 |
|
| 8925 |
:Architectures: ppc |
| 8926 |
|
| 8927 |
This capability, if KVM_CHECK_EXTENSION indicates that it is |
| 8928 |
available, means that the kernel can support guests using the |
| 8929 |
radix MMU defined in Power ISA V3.00 (as implemented in the POWER9 |
| 8930 |
processor). |
| 8931 |
|
| 8932 |
8.4 KVM_CAP_PPC_MMU_HASH_V3 |
| 8933 |
--------------------------- |
| 8934 |
|
| 8935 |
:Architectures: ppc |
| 8936 |
|
| 8937 |
This capability, if KVM_CHECK_EXTENSION indicates that it is |
| 8938 |
available, means that the kernel can support guests using the |
| 8939 |
hashed page table MMU defined in Power ISA V3.00 (as implemented in |
| 8940 |
the POWER9 processor), including in-memory segment tables. |
| 8941 |
|
| 8942 |
8.5 KVM_CAP_MIPS_VZ |
| 8943 |
------------------- |
| 8944 |
|
| 8945 |
:Architectures: mips |
| 8946 |
|
| 8947 |
This capability, if KVM_CHECK_EXTENSION on the main kvm handle indicates that |
| 8948 |
it is available, means that full hardware assisted virtualization capabilities |
| 8949 |
of the hardware are available for use through KVM. An appropriate |
| 8950 |
KVM_VM_MIPS_* type must be passed to KVM_CREATE_VM to create a VM which |
| 8951 |
utilises it. |
| 8952 |
|
| 8953 |
If KVM_CHECK_EXTENSION on a kvm VM handle indicates that this capability is |
| 8954 |
available, it means that the VM is using full hardware assisted virtualization |
| 8955 |
capabilities of the hardware. This is useful to check after creating a VM with |
| 8956 |
KVM_VM_MIPS_DEFAULT. |
| 8957 |
|
| 8958 |
The value returned by KVM_CHECK_EXTENSION should be compared against known |
| 8959 |
values (see below). All other values are reserved. This is to allow for the |
| 8960 |
possibility of other hardware assisted virtualization implementations which |
| 8961 |
may be incompatible with the MIPS VZ ASE. |
| 8962 |
|
| 8963 |
== ========================================================================== |
| 8964 |
0 The trap & emulate implementation is in use to run guest code in user |
| 8965 |
mode. Guest virtual memory segments are rearranged to fit the guest in the |
| 8966 |
user mode address space. |
| 8967 |
|
| 8968 |
1 The MIPS VZ ASE is in use, providing full hardware assisted |
| 8969 |
virtualization, including standard guest virtual memory segments. |
| 8970 |
== ========================================================================== |
| 8971 |
|
| 8972 |
8.7 KVM_CAP_MIPS_64BIT |
| 8973 |
---------------------- |
| 8974 |
|
| 8975 |
:Architectures: mips |
| 8976 |
|
| 8977 |
This capability indicates the supported architecture type of the guest, i.e. the |
| 8978 |
supported register and address width. |
| 8979 |
|
| 8980 |
The values returned when this capability is checked by KVM_CHECK_EXTENSION on a |
| 8981 |
kvm VM handle correspond roughly to the CP0_Config.AT register field, and should |
| 8982 |
be checked specifically against known values (see below). All other values are |
| 8983 |
reserved. |
| 8984 |
|
| 8985 |
== ======================================================================== |
| 8986 |
0 MIPS32 or microMIPS32. |
| 8987 |
Both registers and addresses are 32-bits wide. |
| 8988 |
It will only be possible to run 32-bit guest code. |
| 8989 |
|
| 8990 |
1 MIPS64 or microMIPS64 with access only to 32-bit compatibility segments. |
| 8991 |
Registers are 64-bits wide, but addresses are 32-bits wide. |
| 8992 |
64-bit guest code may run but cannot access MIPS64 memory segments. |
| 8993 |
It will also be possible to run 32-bit guest code. |
| 8994 |
|
| 8995 |
2 MIPS64 or microMIPS64 with access to all address segments. |
| 8996 |
Both registers and addresses are 64-bits wide. |
| 8997 |
It will be possible to run 64-bit or 32-bit guest code. |
| 8998 |
== ======================================================================== |
| 8999 |
|
| 9000 |
8.9 KVM_CAP_ARM_USER_IRQ |
| 9001 |
------------------------ |
| 9002 |
|
| 9003 |
:Architectures: arm64 |
| 9004 |
|
| 9005 |
This capability, if KVM_CHECK_EXTENSION indicates that it is available, means |
| 9006 |
that if userspace creates a VM without an in-kernel interrupt controller, it |
| 9007 |
will be notified of changes to the output level of in-kernel emulated devices, |
| 9008 |
which can generate virtual interrupts, presented to the VM. |
| 9009 |
For such VMs, on every return to userspace, the kernel |
| 9010 |
updates the vcpu's run->s.regs.device_irq_level field to represent the actual |
| 9011 |
output level of the device. |
| 9012 |
|
| 9013 |
Whenever kvm detects a change in the device output level, kvm guarantees at |
| 9014 |
least one return to userspace before running the VM. This exit could either |
| 9015 |
be a KVM_EXIT_INTR or any other exit event, like KVM_EXIT_MMIO. This way, |
| 9016 |
userspace can always sample the device output level and re-compute the state of |
| 9017 |
the userspace interrupt controller. Userspace should always check the state |
| 9018 |
of run->s.regs.device_irq_level on every kvm exit. |
| 9019 |
The value in run->s.regs.device_irq_level can represent both level and edge |
| 9020 |
triggered interrupt signals, depending on the device. Edge triggered interrupt |
| 9021 |
signals will exit to userspace with the bit in run->s.regs.device_irq_level |
| 9022 |
set exactly once per edge signal. |
| 9023 |
|
| 9024 |
The field run->s.regs.device_irq_level is available independent of |
| 9025 |
run->kvm_valid_regs or run->kvm_dirty_regs bits. |
| 9026 |
|
| 9027 |
If KVM_CAP_ARM_USER_IRQ is supported, the KVM_CHECK_EXTENSION ioctl returns a |
| 9028 |
number larger than 0 indicating the version of this capability is implemented |
| 9029 |
and thereby which bits in run->s.regs.device_irq_level can signal values. |
| 9030 |
|
| 9031 |
Currently the following bits are defined for the device_irq_level bitmap:: |
| 9032 |
|
| 9033 |
KVM_CAP_ARM_USER_IRQ >= 1: |
| 9034 |
|
| 9035 |
KVM_ARM_DEV_EL1_VTIMER - EL1 virtual timer |
| 9036 |
KVM_ARM_DEV_EL1_PTIMER - EL1 physical timer |
| 9037 |
KVM_ARM_DEV_PMU - ARM PMU overflow interrupt signal |
| 9038 |
|
| 9039 |
Future versions of kvm may implement additional events. These will get |
| 9040 |
indicated by returning a higher number from KVM_CHECK_EXTENSION and will be |
| 9041 |
listed above. |
| 9042 |
|
| 9043 |
8.10 KVM_CAP_PPC_SMT_POSSIBLE |
| 9044 |
----------------------------- |
| 9045 |
|
| 9046 |
:Architectures: ppc |
| 9047 |
|
| 9048 |
Querying this capability returns a bitmap indicating the possible |
| 9049 |
virtual SMT modes that can be set using KVM_CAP_PPC_SMT. If bit N |
| 9050 |
(counting from the right) is set, then a virtual SMT mode of 2^N is |
| 9051 |
available. |
| 9052 |
|
| 9053 |
8.12 KVM_CAP_HYPERV_VP_INDEX |
| 9054 |
---------------------------- |
| 9055 |
|
| 9056 |
:Architectures: x86 |
| 9057 |
|
| 9058 |
This capability indicates that userspace can load HV_X64_MSR_VP_INDEX msr. Its |
| 9059 |
value is used to denote the target vcpu for a SynIC interrupt. For |
| 9060 |
compatibility, KVM initializes this msr to KVM's internal vcpu index. When this |
| 9061 |
capability is absent, userspace can still query this msr's value. |
| 9062 |
|
| 9063 |
8.13 KVM_CAP_S390_AIS_MIGRATION |
| 9064 |
------------------------------- |
| 9065 |
|
| 9066 |
:Architectures: s390 |
| 9067 |
|
| 9068 |
This capability indicates if the flic device will be able to get/set the |
| 9069 |
AIS states for migration via the KVM_DEV_FLIC_AISM_ALL attribute and allows |
| 9070 |
to discover this without having to create a flic device. |
| 9071 |
|
| 9072 |
8.14 KVM_CAP_S390_PSW |
| 9073 |
--------------------- |
| 9074 |
|
| 9075 |
:Architectures: s390 |
| 9076 |
|
| 9077 |
This capability indicates that the PSW is exposed via the kvm_run structure. |
| 9078 |
|
| 9079 |
8.15 KVM_CAP_S390_GMAP |
| 9080 |
---------------------- |
| 9081 |
|
| 9082 |
:Architectures: s390 |
| 9083 |
|
| 9084 |
This capability indicates that the user space memory used as guest mapping can |
| 9085 |
be anywhere in the user memory address space, as long as the memory slots are |
| 9086 |
aligned and sized to a segment (1MB) boundary. |
| 9087 |
|
| 9088 |
8.16 KVM_CAP_S390_COW |
| 9089 |
--------------------- |
| 9090 |
|
| 9091 |
:Architectures: s390 |
| 9092 |
|
| 9093 |
This capability indicates that the user space memory used as guest mapping can |
| 9094 |
use copy-on-write semantics as well as dirty pages tracking via read-only page |
| 9095 |
tables. |
| 9096 |
|
| 9097 |
8.17 KVM_CAP_S390_BPB |
| 9098 |
--------------------- |
| 9099 |
|
| 9100 |
:Architectures: s390 |
| 9101 |
|
| 9102 |
This capability indicates that kvm will implement the interfaces to handle |
| 9103 |
reset, migration and nested KVM for branch prediction blocking. The stfle |
| 9104 |
facility 82 should not be provided to the guest without this capability. |
| 9105 |
|
| 9106 |
8.18 KVM_CAP_HYPERV_TLBFLUSH |
| 9107 |
---------------------------- |
| 9108 |
|
| 9109 |
:Architectures: x86 |
| 9110 |
|
| 9111 |
This capability indicates that KVM supports paravirtualized Hyper-V TLB Flush |
| 9112 |
hypercalls: |
| 9113 |
HvFlushVirtualAddressSpace, HvFlushVirtualAddressSpaceEx, |
| 9114 |
HvFlushVirtualAddressList, HvFlushVirtualAddressListEx. |
| 9115 |
|
| 9116 |
8.19 KVM_CAP_ARM_INJECT_SERROR_ESR |
| 9117 |
---------------------------------- |
| 9118 |
|
| 9119 |
:Architectures: arm64 |
| 9120 |
|
| 9121 |
This capability indicates that userspace can specify (via the |
| 9122 |
KVM_SET_VCPU_EVENTS ioctl) the syndrome value reported to the guest when it |
| 9123 |
takes a virtual SError interrupt exception. |
| 9124 |
If KVM advertises this capability, userspace can only specify the ISS field for |
| 9125 |
the ESR syndrome. Other parts of the ESR, such as the EC are generated by the |
| 9126 |
CPU when the exception is taken. If this virtual SError is taken to EL1 using |
| 9127 |
AArch64, this value will be reported in the ISS field of ESR_ELx. |
| 9128 |
|
| 9129 |
See KVM_CAP_VCPU_EVENTS for more details. |
| 9130 |
|
| 9131 |
8.20 KVM_CAP_HYPERV_SEND_IPI |
| 9132 |
---------------------------- |
| 9133 |
|
| 9134 |
:Architectures: x86 |
| 9135 |
|
| 9136 |
This capability indicates that KVM supports paravirtualized Hyper-V IPI send |
| 9137 |
hypercalls: |
| 9138 |
HvCallSendSyntheticClusterIpi, HvCallSendSyntheticClusterIpiEx. |
| 9139 |
|
| 9140 |
8.22 KVM_CAP_S390_VCPU_RESETS |
| 9141 |
----------------------------- |
| 9142 |
|
| 9143 |
:Architectures: s390 |
| 9144 |
|
| 9145 |
This capability indicates that the KVM_S390_NORMAL_RESET and |
| 9146 |
KVM_S390_CLEAR_RESET ioctls are available. |
| 9147 |
|
| 9148 |
8.23 KVM_CAP_S390_PROTECTED |
| 9149 |
--------------------------- |
| 9150 |
|
| 9151 |
:Architectures: s390 |
| 9152 |
|
| 9153 |
This capability indicates that the Ultravisor has been initialized and |
| 9154 |
KVM can therefore start protected VMs. |
| 9155 |
This capability governs the KVM_S390_PV_COMMAND ioctl and the |
| 9156 |
KVM_MP_STATE_LOAD MP_STATE. KVM_SET_MP_STATE can fail for protected |
| 9157 |
guests when the state change is invalid. |
| 9158 |
|
| 9159 |
8.24 KVM_CAP_STEAL_TIME |
| 9160 |
----------------------- |
| 9161 |
|
| 9162 |
:Architectures: arm64, x86 |
| 9163 |
|
| 9164 |
This capability indicates that KVM supports steal time accounting. |
| 9165 |
When steal time accounting is supported it may be enabled with |
| 9166 |
architecture-specific interfaces. This capability and the architecture- |
| 9167 |
specific interfaces must be consistent, i.e. if one says the feature |
| 9168 |
is supported, than the other should as well and vice versa. For arm64 |
| 9169 |
see Documentation/virt/kvm/devices/vcpu.rst "KVM_ARM_VCPU_PVTIME_CTRL". |
| 9170 |
For x86 see Documentation/virt/kvm/x86/msr.rst "MSR_KVM_STEAL_TIME". |
| 9171 |
|
| 9172 |
8.25 KVM_CAP_S390_DIAG318 |
| 9173 |
------------------------- |
| 9174 |
|
| 9175 |
:Architectures: s390 |
| 9176 |
|
| 9177 |
This capability enables a guest to set information about its control program |
| 9178 |
(i.e. guest kernel type and version). The information is helpful during |
| 9179 |
system/firmware service events, providing additional data about the guest |
| 9180 |
environments running on the machine. |
| 9181 |
|
| 9182 |
The information is associated with the DIAGNOSE 0x318 instruction, which sets |
| 9183 |
an 8-byte value consisting of a one-byte Control Program Name Code (CPNC) and |
| 9184 |
a 7-byte Control Program Version Code (CPVC). The CPNC determines what |
| 9185 |
environment the control program is running in (e.g. Linux, z/VM...), and the |
| 9186 |
CPVC is used for information specific to OS (e.g. Linux version, Linux |
| 9187 |
distribution...) |
| 9188 |
|
| 9189 |
If this capability is available, then the CPNC and CPVC can be synchronized |
| 9190 |
between KVM and userspace via the sync regs mechanism (KVM_SYNC_DIAG318). |
| 9191 |
|
| 9192 |
8.26 KVM_CAP_X86_USER_SPACE_MSR |
| 9193 |
------------------------------- |
| 9194 |
|
| 9195 |
:Architectures: x86 |
| 9196 |
|
| 9197 |
This capability indicates that KVM supports deflection of MSR reads and |
| 9198 |
writes to user space. It can be enabled on a VM level. If enabled, MSR |
| 9199 |
accesses that would usually trigger a #GP by KVM into the guest will |
| 9200 |
instead get bounced to user space through the KVM_EXIT_X86_RDMSR and |
| 9201 |
KVM_EXIT_X86_WRMSR exit notifications. |
| 9202 |
|
| 9203 |
8.27 KVM_CAP_X86_MSR_FILTER |
| 9204 |
--------------------------- |
| 9205 |
|
| 9206 |
:Architectures: x86 |
| 9207 |
|
| 9208 |
This capability indicates that KVM supports that accesses to user defined MSRs |
| 9209 |
may be rejected. With this capability exposed, KVM exports new VM ioctl |
| 9210 |
KVM_X86_SET_MSR_FILTER which user space can call to specify bitmaps of MSR |
| 9211 |
ranges that KVM should deny access to. |
| 9212 |
|
| 9213 |
In combination with KVM_CAP_X86_USER_SPACE_MSR, this allows user space to |
| 9214 |
trap and emulate MSRs that are outside of the scope of KVM as well as |
| 9215 |
limit the attack surface on KVM's MSR emulation code. |
| 9216 |
|
| 9217 |
8.30 KVM_CAP_XEN_HVM |
| 9218 |
-------------------- |
| 9219 |
|
| 9220 |
:Architectures: x86 |
| 9221 |
|
| 9222 |
This capability indicates the features that Xen supports for hosting Xen |
| 9223 |
PVHVM guests. Valid flags are:: |
| 9224 |
|
| 9225 |
#define KVM_XEN_HVM_CONFIG_HYPERCALL_MSR (1 << 0) |
| 9226 |
#define KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL (1 << 1) |
| 9227 |
#define KVM_XEN_HVM_CONFIG_SHARED_INFO (1 << 2) |
| 9228 |
#define KVM_XEN_HVM_CONFIG_RUNSTATE (1 << 3) |
| 9229 |
#define KVM_XEN_HVM_CONFIG_EVTCHN_2LEVEL (1 << 4) |
| 9230 |
#define KVM_XEN_HVM_CONFIG_EVTCHN_SEND (1 << 5) |
| 9231 |
#define KVM_XEN_HVM_CONFIG_RUNSTATE_UPDATE_FLAG (1 << 6) |
| 9232 |
#define KVM_XEN_HVM_CONFIG_PVCLOCK_TSC_UNSTABLE (1 << 7) |
| 9233 |
|
| 9234 |
The KVM_XEN_HVM_CONFIG_HYPERCALL_MSR flag indicates that the KVM_XEN_HVM_CONFIG |
| 9235 |
ioctl is available, for the guest to set its hypercall page. |
| 9236 |
|
| 9237 |
If KVM_XEN_HVM_CONFIG_INTERCEPT_HCALL is also set, the same flag may also be |
| 9238 |
provided in the flags to KVM_XEN_HVM_CONFIG, without providing hypercall page |
| 9239 |
contents, to request that KVM generate hypercall page content automatically |
| 9240 |
and also enable interception of guest hypercalls with KVM_EXIT_XEN. |
| 9241 |
|
| 9242 |
The KVM_XEN_HVM_CONFIG_SHARED_INFO flag indicates the availability of the |
| 9243 |
KVM_XEN_HVM_SET_ATTR, KVM_XEN_HVM_GET_ATTR, KVM_XEN_VCPU_SET_ATTR and |
| 9244 |
KVM_XEN_VCPU_GET_ATTR ioctls, as well as the delivery of exception vectors |
| 9245 |
for event channel upcalls when the evtchn_upcall_pending field of a vcpu's |
| 9246 |
vcpu_info is set. |
| 9247 |
|
| 9248 |
The KVM_XEN_HVM_CONFIG_RUNSTATE flag indicates that the runstate-related |
| 9249 |
features KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADDR/_CURRENT/_DATA/_ADJUST are |
| 9250 |
supported by the KVM_XEN_VCPU_SET_ATTR/KVM_XEN_VCPU_GET_ATTR ioctls. |
| 9251 |
|
| 9252 |
The KVM_XEN_HVM_CONFIG_EVTCHN_2LEVEL flag indicates that IRQ routing entries |
| 9253 |
of the type KVM_IRQ_ROUTING_XEN_EVTCHN are supported, with the priority |
| 9254 |
field set to indicate 2 level event channel delivery. |
| 9255 |
|
| 9256 |
The KVM_XEN_HVM_CONFIG_EVTCHN_SEND flag indicates that KVM supports |
| 9257 |
injecting event channel events directly into the guest with the |
| 9258 |
KVM_XEN_HVM_EVTCHN_SEND ioctl. It also indicates support for the |
| 9259 |
KVM_XEN_ATTR_TYPE_EVTCHN/XEN_VERSION HVM attributes and the |
| 9260 |
KVM_XEN_VCPU_ATTR_TYPE_VCPU_ID/TIMER/UPCALL_VECTOR vCPU attributes. |
| 9261 |
related to event channel delivery, timers, and the XENVER_version |
| 9262 |
interception. |
| 9263 |
|
| 9264 |
The KVM_XEN_HVM_CONFIG_RUNSTATE_UPDATE_FLAG flag indicates that KVM supports |
| 9265 |
the KVM_XEN_ATTR_TYPE_RUNSTATE_UPDATE_FLAG attribute in the KVM_XEN_SET_ATTR |
| 9266 |
and KVM_XEN_GET_ATTR ioctls. This controls whether KVM will set the |
| 9267 |
XEN_RUNSTATE_UPDATE flag in guest memory mapped vcpu_runstate_info during |
| 9268 |
updates of the runstate information. Note that versions of KVM which support |
| 9269 |
the RUNSTATE feature above, but not the RUNSTATE_UPDATE_FLAG feature, will |
| 9270 |
always set the XEN_RUNSTATE_UPDATE flag when updating the guest structure, |
| 9271 |
which is perhaps counterintuitive. When this flag is advertised, KVM will |
| 9272 |
behave more correctly, not using the XEN_RUNSTATE_UPDATE flag until/unless |
| 9273 |
specifically enabled (by the guest making the hypercall, causing the VMM |
| 9274 |
to enable the KVM_XEN_ATTR_TYPE_RUNSTATE_UPDATE_FLAG attribute). |
| 9275 |
|
| 9276 |
The KVM_XEN_HVM_CONFIG_PVCLOCK_TSC_UNSTABLE flag indicates that KVM supports |
| 9277 |
clearing the PVCLOCK_TSC_STABLE_BIT flag in Xen pvclock sources. This will be |
| 9278 |
done when the KVM_CAP_XEN_HVM ioctl sets the |
| 9279 |
KVM_XEN_HVM_CONFIG_PVCLOCK_TSC_UNSTABLE flag. |
| 9280 |
|
| 9281 |
8.31 KVM_CAP_SPAPR_MULTITCE |
| 9282 |
--------------------------- |
| 9283 |
|
| 9284 |
:Architectures: ppc |
| 9285 |
:Type: vm |
| 9286 |
|
| 9287 |
This capability means the kernel is capable of handling hypercalls |
| 9288 |
H_PUT_TCE_INDIRECT and H_STUFF_TCE without passing those into the user |
| 9289 |
space. This significantly accelerates DMA operations for PPC KVM guests. |
| 9290 |
User space should expect that its handlers for these hypercalls |
| 9291 |
are not going to be called if user space previously registered LIOBN |
| 9292 |
in KVM (via KVM_CREATE_SPAPR_TCE or similar calls). |
| 9293 |
|
| 9294 |
In order to enable H_PUT_TCE_INDIRECT and H_STUFF_TCE use in the guest, |
| 9295 |
user space might have to advertise it for the guest. For example, |
| 9296 |
IBM pSeries (sPAPR) guest starts using them if "hcall-multi-tce" is |
| 9297 |
present in the "ibm,hypertas-functions" device-tree property. |
| 9298 |
|
| 9299 |
The hypercalls mentioned above may or may not be processed successfully |
| 9300 |
in the kernel based fast path. If they can not be handled by the kernel, |
| 9301 |
they will get passed on to user space. So user space still has to have |
| 9302 |
an implementation for these despite the in kernel acceleration. |
| 9303 |
|
| 9304 |
This capability is always enabled. |
| 9305 |
|
| 9306 |
8.32 KVM_CAP_PTP_KVM |
| 9307 |
-------------------- |
| 9308 |
|
| 9309 |
:Architectures: arm64 |
| 9310 |
|
| 9311 |
This capability indicates that the KVM virtual PTP service is |
| 9312 |
supported in the host. A VMM can check whether the service is |
| 9313 |
available to the guest on migration. |
| 9314 |
|
| 9315 |
8.37 KVM_CAP_S390_PROTECTED_DUMP |
| 9316 |
-------------------------------- |
| 9317 |
|
| 9318 |
:Architectures: s390 |
| 9319 |
:Type: vm |
| 9320 |
|
| 9321 |
This capability indicates that KVM and the Ultravisor support dumping |
| 9322 |
PV guests. The `KVM_PV_DUMP` command is available for the |
| 9323 |
`KVM_S390_PV_COMMAND` ioctl and the `KVM_PV_INFO` command provides |
| 9324 |
dump related UV data. Also the vcpu ioctl `KVM_S390_PV_CPU_COMMAND` is |
| 9325 |
available and supports the `KVM_PV_DUMP_CPU` subcommand. |
| 9326 |
|
| 9327 |
8.39 KVM_CAP_S390_CPU_TOPOLOGY |
| 9328 |
------------------------------ |
| 9329 |
|
| 9330 |
:Architectures: s390 |
| 9331 |
:Type: vm |
| 9332 |
|
| 9333 |
This capability indicates that KVM will provide the S390 CPU Topology |
| 9334 |
facility which consist of the interpretation of the PTF instruction for |
| 9335 |
the function code 2 along with interception and forwarding of both the |
| 9336 |
PTF instruction with function codes 0 or 1 and the STSI(15,1,x) |
| 9337 |
instruction to the userland hypervisor. |
| 9338 |
|
| 9339 |
The stfle facility 11, CPU Topology facility, should not be indicated |
| 9340 |
to the guest without this capability. |
| 9341 |
|
| 9342 |
When this capability is present, KVM provides a new attribute group |
| 9343 |
on vm fd, KVM_S390_VM_CPU_TOPOLOGY. |
| 9344 |
This new attribute allows to get, set or clear the Modified Change |
| 9345 |
Topology Report (MTCR) bit of the SCA through the kvm_device_attr |
| 9346 |
structure. |
| 9347 |
|
| 9348 |
When getting the Modified Change Topology Report value, the attr->addr |
| 9349 |
must point to a byte where the value will be stored or retrieved from. |
| 9350 |
|
| 9351 |
8.41 KVM_CAP_VM_TYPES |
| 9352 |
--------------------- |
| 9353 |
|
| 9354 |
:Architectures: x86 |
| 9355 |
:Type: system ioctl |
| 9356 |
|
| 9357 |
This capability returns a bitmap of support VM types. The 1-setting of bit @n |
| 9358 |
means the VM type with value @n is supported. Possible values of @n are:: |
| 9359 |
|
| 9360 |
#define KVM_X86_DEFAULT_VM 0 |
| 9361 |
#define KVM_X86_SW_PROTECTED_VM 1 |
| 9362 |
#define KVM_X86_SEV_VM 2 |
| 9363 |
#define KVM_X86_SEV_ES_VM 3 |
| 9364 |
|
| 9365 |
Note, KVM_X86_SW_PROTECTED_VM is currently only for development and testing. |
| 9366 |
Do not use KVM_X86_SW_PROTECTED_VM for "real" VMs, and especially not in |
| 9367 |
production. The behavior and effective ABI for software-protected VMs is |
| 9368 |
unstable. |
| 9369 |
|
| 9370 |
8.42 KVM_CAP_PPC_RPT_INVALIDATE |
| 9371 |
------------------------------- |
| 9372 |
|
| 9373 |
:Architectures: ppc |
| 9374 |
|
| 9375 |
This capability indicates that the kernel is capable of handling |
| 9376 |
H_RPT_INVALIDATE hcall. |
| 9377 |
|
| 9378 |
In order to enable the use of H_RPT_INVALIDATE in the guest, |
| 9379 |
user space might have to advertise it for the guest. For example, |
| 9380 |
IBM pSeries (sPAPR) guest starts using it if "hcall-rpt-invalidate" is |
| 9381 |
present in the "ibm,hypertas-functions" device-tree property. |
| 9382 |
|
| 9383 |
This capability is enabled for hypervisors on platforms like POWER9 |
| 9384 |
that support radix MMU. |
| 9385 |
|
| 9386 |
8.43 KVM_CAP_PPC_AIL_MODE_3 |
| 9387 |
--------------------------- |
| 9388 |
|
| 9389 |
:Architectures: ppc |
| 9390 |
|
| 9391 |
This capability indicates that the kernel supports the mode 3 setting for the |
| 9392 |
"Address Translation Mode on Interrupt" aka "Alternate Interrupt Location" |
| 9393 |
resource that is controlled with the H_SET_MODE hypercall. |
| 9394 |
|
| 9395 |
This capability allows a guest kernel to use a better-performance mode for |
| 9396 |
handling interrupts and system calls. |
| 9397 |
|
| 9398 |
8.44 KVM_CAP_MEMORY_FAULT_INFO |
| 9399 |
------------------------------ |
| 9400 |
|
| 9401 |
:Architectures: x86 |
| 9402 |
|
| 9403 |
The presence of this capability indicates that KVM_RUN will fill |
| 9404 |
kvm_run.memory_fault if KVM cannot resolve a guest page fault VM-Exit, e.g. if |
| 9405 |
there is a valid memslot but no backing VMA for the corresponding host virtual |
| 9406 |
address. |
| 9407 |
|
| 9408 |
The information in kvm_run.memory_fault is valid if and only if KVM_RUN returns |
| 9409 |
an error with errno=EFAULT or errno=EHWPOISON *and* kvm_run.exit_reason is set |
| 9410 |
to KVM_EXIT_MEMORY_FAULT. |
| 9411 |
|
| 9412 |
Note: Userspaces which attempt to resolve memory faults so that they can retry |
| 9413 |
KVM_RUN are encouraged to guard against repeatedly receiving the same |
| 9414 |
error/annotated fault. |
| 9415 |
|
| 9416 |
See KVM_EXIT_MEMORY_FAULT for more information. |
| 9417 |
|
| 9418 |
8.45 KVM_CAP_X86_GUEST_MODE |
| 9419 |
--------------------------- |
| 9420 |
|
| 9421 |
:Architectures: x86 |
| 9422 |
|
| 9423 |
The presence of this capability indicates that KVM_RUN will update the |
| 9424 |
KVM_RUN_X86_GUEST_MODE bit in kvm_run.flags to indicate whether the |
| 9425 |
vCPU was executing nested guest code when it exited. |
| 9426 |
|
| 9427 |
8.46 KVM_CAP_S390_KEYOP |
| 9428 |
----------------------- |
| 9429 |
|
| 9430 |
:Architectures: s390 |
| 9431 |
|
| 9432 |
The presence of this capability indicates that the KVM_S390_KEYOP ioctl is |
| 9433 |
available. |
| 9434 |
|
| 9435 |
KVM exits with the register state of either the L1 or L2 guest |
| 9436 |
depending on which executed at the time of an exit. Userspace must |
| 9437 |
take care to differentiate between these cases. |
| 9438 |
|
| 9439 |
9. Known KVM API problems |
| 9440 |
========================= |
| 9441 |
|
| 9442 |
In some cases, KVM's API has some inconsistencies or common pitfalls |
| 9443 |
that userspace need to be aware of. This section details some of |
| 9444 |
these issues. |
| 9445 |
|
| 9446 |
Most of them are architecture specific, so the section is split by |
| 9447 |
architecture. |
| 9448 |
|
| 9449 |
9.1. x86 |
| 9450 |
-------- |
| 9451 |
|
| 9452 |
``KVM_GET_SUPPORTED_CPUID`` issues |
| 9453 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 9454 |
|
| 9455 |
In general, ``KVM_GET_SUPPORTED_CPUID`` is designed so that it is possible |
| 9456 |
to take its result and pass it directly to ``KVM_SET_CPUID2``. This section |
| 9457 |
documents some cases in which that requires some care. |
| 9458 |
|
| 9459 |
Local APIC features |
| 9460 |
~~~~~~~~~~~~~~~~~~~ |
| 9461 |
|
| 9462 |
CPU[EAX=1]:ECX[21] (X2APIC) is reported by ``KVM_GET_SUPPORTED_CPUID``, |
| 9463 |
but it can only be enabled if ``KVM_CREATE_IRQCHIP`` or |
| 9464 |
``KVM_ENABLE_CAP(KVM_CAP_IRQCHIP_SPLIT)`` are used to enable in-kernel emulation of |
| 9465 |
the local APIC. |
| 9466 |
|
| 9467 |
The same is true for the ``KVM_FEATURE_PV_UNHALT`` paravirtualized feature. |
| 9468 |
|
| 9469 |
On older versions of Linux, CPU[EAX=1]:ECX[24] (TSC_DEADLINE) is not reported by |
| 9470 |
``KVM_GET_SUPPORTED_CPUID``, but it can be enabled if ``KVM_CAP_TSC_DEADLINE_TIMER`` |
| 9471 |
is present and the kernel has enabled in-kernel emulation of the local APIC. |
| 9472 |
On newer versions, ``KVM_GET_SUPPORTED_CPUID`` does report the bit as available. |
| 9473 |
|
| 9474 |
CPU topology |
| 9475 |
~~~~~~~~~~~~ |
| 9476 |
|
| 9477 |
Several CPUID values include topology information for the host CPU: |
| 9478 |
0x0b and 0x1f for Intel systems, 0x8000001e for AMD systems. Different |
| 9479 |
versions of KVM return different values for this information and userspace |
| 9480 |
should not rely on it. Currently they return all zeroes. |
| 9481 |
|
| 9482 |
If userspace wishes to set up a guest topology, it should be careful that |
| 9483 |
the values of these three leaves differ for each CPU. In particular, |
| 9484 |
the APIC ID is found in EDX for all subleaves of 0x0b and 0x1f, and in EAX |
| 9485 |
for 0x8000001e; the latter also encodes the core id and node id in bits |
| 9486 |
7:0 of EBX and ECX respectively. |
| 9487 |
|
| 9488 |
Obsolete ioctls and capabilities |
| 9489 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 9490 |
|
| 9491 |
KVM_CAP_DISABLE_QUIRKS does not let userspace know which quirks are actually |
| 9492 |
available. Use ``KVM_CHECK_EXTENSION(KVM_CAP_DISABLE_QUIRKS2)`` instead if |
| 9493 |
available. |
| 9494 |
|
| 9495 |
Ordering of KVM_GET_*/KVM_SET_* ioctls |
| 9496 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 9497 |
|
| 9498 |
TBD |