Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 1 | The Definitive KVM (Kernel-based Virtual Machine) API Documentation |
| 2 | =================================================================== |
| 3 | |
| 4 | 1. General description |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 5 | ---------------------- |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 6 | |
| 7 | The kvm API is a set of ioctls that are issued to control various aspects |
| 8 | of a virtual machine. The ioctls belong to three classes |
| 9 | |
| 10 | - System ioctls: These query and set global attributes which affect the |
| 11 | whole kvm subsystem. In addition a system ioctl is used to create |
| 12 | virtual machines |
| 13 | |
| 14 | - VM ioctls: These query and set attributes that affect an entire virtual |
| 15 | machine, for example memory layout. In addition a VM ioctl is used to |
| 16 | create virtual cpus (vcpus). |
| 17 | |
| 18 | Only run VM ioctls from the same process (address space) that was used |
| 19 | to create the VM. |
| 20 | |
| 21 | - vcpu ioctls: These query and set attributes that control the operation |
| 22 | of a single virtual cpu. |
| 23 | |
| 24 | Only run vcpu ioctls from the same thread that was used to create the |
| 25 | vcpu. |
| 26 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 27 | |
Wu Fengguang | 2044892d | 2009-12-24 09:04:16 +0800 | [diff] [blame] | 28 | 2. File descriptors |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 29 | ------------------- |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 30 | |
| 31 | The kvm API is centered around file descriptors. An initial |
| 32 | open("/dev/kvm") obtains a handle to the kvm subsystem; this handle |
| 33 | can be used to issue system ioctls. A KVM_CREATE_VM ioctl on this |
Wu Fengguang | 2044892d | 2009-12-24 09:04:16 +0800 | [diff] [blame] | 34 | handle will create a VM file descriptor which can be used to issue VM |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 35 | ioctls. A KVM_CREATE_VCPU ioctl on a VM fd will create a virtual cpu |
| 36 | and return a file descriptor pointing to it. Finally, ioctls on a vcpu |
| 37 | fd can be used to control the vcpu, including the important task of |
| 38 | actually running guest code. |
| 39 | |
| 40 | In general file descriptors can be migrated among processes by means |
| 41 | of fork() and the SCM_RIGHTS facility of unix domain socket. These |
| 42 | kinds of tricks are explicitly not supported by kvm. While they will |
| 43 | not cause harm to the host, their actual behavior is not guaranteed by |
| 44 | the API. The only supported use is one virtual machine per process, |
| 45 | and one vcpu per thread. |
| 46 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 47 | |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 48 | 3. Extensions |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 49 | ------------- |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 50 | |
| 51 | As of Linux 2.6.22, the KVM ABI has been stabilized: no backward |
| 52 | incompatible change are allowed. However, there is an extension |
| 53 | facility that allows backward-compatible extensions to the API to be |
| 54 | queried and used. |
| 55 | |
| 56 | The extension mechanism is not based on on the Linux version number. |
| 57 | Instead, kvm defines extension identifiers and a facility to query |
| 58 | whether a particular extension identifier is available. If it is, a |
| 59 | set of ioctls is available for application use. |
| 60 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 61 | |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 62 | 4. API description |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 63 | ------------------ |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 64 | |
| 65 | This section describes ioctls that can be used to control kvm guests. |
| 66 | For each ioctl, the following information is provided along with a |
| 67 | description: |
| 68 | |
| 69 | Capability: which KVM extension provides this ioctl. Can be 'basic', |
| 70 | which means that is will be provided by any kernel that supports |
| 71 | API version 12 (see section 4.1), or a KVM_CAP_xyz constant, which |
| 72 | means availability needs to be checked with KVM_CHECK_EXTENSION |
| 73 | (see section 4.4). |
| 74 | |
| 75 | Architectures: which instruction set architectures provide this ioctl. |
| 76 | x86 includes both i386 and x86_64. |
| 77 | |
| 78 | Type: system, vm, or vcpu. |
| 79 | |
| 80 | Parameters: what parameters are accepted by the ioctl. |
| 81 | |
| 82 | Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL) |
| 83 | are not detailed, but errors with specific meanings are. |
| 84 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 85 | |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 86 | 4.1 KVM_GET_API_VERSION |
| 87 | |
| 88 | Capability: basic |
| 89 | Architectures: all |
| 90 | Type: system ioctl |
| 91 | Parameters: none |
| 92 | Returns: the constant KVM_API_VERSION (=12) |
| 93 | |
| 94 | This identifies the API version as the stable kvm API. It is not |
| 95 | expected that this number will change. However, Linux 2.6.20 and |
| 96 | 2.6.21 report earlier versions; these are not documented and not |
| 97 | supported. Applications should refuse to run if KVM_GET_API_VERSION |
| 98 | returns a value other than 12. If this check passes, all ioctls |
| 99 | described as 'basic' will be available. |
| 100 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 101 | |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 102 | 4.2 KVM_CREATE_VM |
| 103 | |
| 104 | Capability: basic |
| 105 | Architectures: all |
| 106 | Type: system ioctl |
Carsten Otte | e08b963 | 2012-01-04 10:25:20 +0100 | [diff] [blame] | 107 | Parameters: machine type identifier (KVM_VM_*) |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 108 | Returns: a VM fd that can be used to control the new virtual machine. |
| 109 | |
| 110 | The new VM has no virtual cpus and no memory. An mmap() of a VM fd |
| 111 | will access the virtual machine's physical address space; offset zero |
| 112 | corresponds to guest physical address zero. Use of mmap() on a VM fd |
| 113 | is discouraged if userspace memory allocation (KVM_CAP_USER_MEMORY) is |
| 114 | available. |
Carsten Otte | e08b963 | 2012-01-04 10:25:20 +0100 | [diff] [blame] | 115 | You most certainly want to use 0 as machine type. |
| 116 | |
| 117 | In order to create user controlled virtual machines on S390, check |
| 118 | KVM_CAP_S390_UCONTROL and use the flag KVM_VM_S390_UCONTROL as |
| 119 | privileged user (CAP_SYS_ADMIN). |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 120 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 121 | |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 122 | 4.3 KVM_GET_MSR_INDEX_LIST |
| 123 | |
| 124 | Capability: basic |
| 125 | Architectures: x86 |
| 126 | Type: system |
| 127 | Parameters: struct kvm_msr_list (in/out) |
| 128 | Returns: 0 on success; -1 on error |
| 129 | Errors: |
| 130 | E2BIG: the msr index list is to be to fit in the array specified by |
| 131 | the user. |
| 132 | |
| 133 | struct kvm_msr_list { |
| 134 | __u32 nmsrs; /* number of msrs in entries */ |
| 135 | __u32 indices[0]; |
| 136 | }; |
| 137 | |
| 138 | This ioctl returns the guest msrs that are supported. The list varies |
| 139 | by kvm version and host processor, but does not change otherwise. The |
| 140 | user fills in the size of the indices array in nmsrs, and in return |
| 141 | kvm adjusts nmsrs to reflect the actual number of msrs and fills in |
| 142 | the indices array with their numbers. |
| 143 | |
Avi Kivity | 2e2602c | 2010-07-07 14:09:39 +0300 | [diff] [blame] | 144 | Note: if kvm indicates supports MCE (KVM_CAP_MCE), then the MCE bank MSRs are |
| 145 | not returned in the MSR list, as different vcpus can have a different number |
| 146 | of banks, as set via the KVM_X86_SETUP_MCE ioctl. |
| 147 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 148 | |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 149 | 4.4 KVM_CHECK_EXTENSION |
| 150 | |
| 151 | Capability: basic |
| 152 | Architectures: all |
| 153 | Type: system ioctl |
| 154 | Parameters: extension identifier (KVM_CAP_*) |
| 155 | Returns: 0 if unsupported; 1 (or some other positive integer) if supported |
| 156 | |
| 157 | The API allows the application to query about extensions to the core |
| 158 | kvm API. Userspace passes an extension identifier (an integer) and |
| 159 | receives an integer that describes the extension availability. |
| 160 | Generally 0 means no and 1 means yes, but some extensions may report |
| 161 | additional information in the integer return value. |
| 162 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 163 | |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 164 | 4.5 KVM_GET_VCPU_MMAP_SIZE |
| 165 | |
| 166 | Capability: basic |
| 167 | Architectures: all |
| 168 | Type: system ioctl |
| 169 | Parameters: none |
| 170 | Returns: size of vcpu mmap area, in bytes |
| 171 | |
| 172 | The KVM_RUN ioctl (cf.) communicates with userspace via a shared |
| 173 | memory region. This ioctl returns the size of that region. See the |
| 174 | KVM_RUN documentation for details. |
| 175 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 176 | |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 177 | 4.6 KVM_SET_MEMORY_REGION |
| 178 | |
| 179 | Capability: basic |
| 180 | Architectures: all |
| 181 | Type: vm ioctl |
| 182 | Parameters: struct kvm_memory_region (in) |
| 183 | Returns: 0 on success, -1 on error |
| 184 | |
Avi Kivity | b74a07b | 2010-06-21 11:48:05 +0300 | [diff] [blame] | 185 | This ioctl is obsolete and has been removed. |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 186 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 187 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 188 | 4.7 KVM_CREATE_VCPU |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 189 | |
| 190 | Capability: basic |
| 191 | Architectures: all |
| 192 | Type: vm ioctl |
| 193 | Parameters: vcpu id (apic id on x86) |
| 194 | Returns: vcpu fd on success, -1 on error |
| 195 | |
| 196 | This API adds a vcpu to a virtual machine. The vcpu id is a small integer |
Sasha Levin | 8c3ba33 | 2011-07-18 17:17:15 +0300 | [diff] [blame] | 197 | in the range [0, max_vcpus). |
| 198 | |
| 199 | The recommended max_vcpus value can be retrieved using the KVM_CAP_NR_VCPUS of |
| 200 | the KVM_CHECK_EXTENSION ioctl() at run-time. |
| 201 | The maximum possible value for max_vcpus can be retrieved using the |
| 202 | KVM_CAP_MAX_VCPUS of the KVM_CHECK_EXTENSION ioctl() at run-time. |
| 203 | |
Pekka Enberg | 76d2540 | 2011-05-09 22:48:54 +0300 | [diff] [blame] | 204 | If the KVM_CAP_NR_VCPUS does not exist, you should assume that max_vcpus is 4 |
| 205 | cpus max. |
Sasha Levin | 8c3ba33 | 2011-07-18 17:17:15 +0300 | [diff] [blame] | 206 | If the KVM_CAP_MAX_VCPUS does not exist, you should assume that max_vcpus is |
| 207 | same as the value returned from KVM_CAP_NR_VCPUS. |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 208 | |
Paul Mackerras | 371fefd | 2011-06-29 00:23:08 +0000 | [diff] [blame] | 209 | On powerpc using book3s_hv mode, the vcpus are mapped onto virtual |
| 210 | threads in one or more virtual CPU cores. (This is because the |
| 211 | hardware requires all the hardware threads in a CPU core to be in the |
| 212 | same partition.) The KVM_CAP_PPC_SMT capability indicates the number |
| 213 | of vcpus per virtual core (vcore). The vcore id is obtained by |
| 214 | dividing the vcpu id by the number of vcpus per vcore. The vcpus in a |
| 215 | given vcore will always be in the same physical core as each other |
| 216 | (though that might be a different physical core from time to time). |
| 217 | Userspace can control the threading (SMT) mode of the guest by its |
| 218 | allocation of vcpu ids. For example, if userspace wants |
| 219 | single-threaded guest vcpus, it should make all vcpu ids be a multiple |
| 220 | of the number of vcpus per vcore. |
| 221 | |
Avi Kivity | 3644268 | 2011-08-29 16:27:08 +0300 | [diff] [blame] | 222 | On powerpc using book3s_hv mode, the vcpus are mapped onto virtual |
| 223 | threads in one or more virtual CPU cores. (This is because the |
| 224 | hardware requires all the hardware threads in a CPU core to be in the |
| 225 | same partition.) The KVM_CAP_PPC_SMT capability indicates the number |
| 226 | of vcpus per virtual core (vcore). The vcore id is obtained by |
| 227 | dividing the vcpu id by the number of vcpus per vcore. The vcpus in a |
| 228 | given vcore will always be in the same physical core as each other |
| 229 | (though that might be a different physical core from time to time). |
| 230 | Userspace can control the threading (SMT) mode of the guest by its |
| 231 | allocation of vcpu ids. For example, if userspace wants |
| 232 | single-threaded guest vcpus, it should make all vcpu ids be a multiple |
| 233 | of the number of vcpus per vcore. |
| 234 | |
Carsten Otte | 5b1c149 | 2012-01-04 10:25:23 +0100 | [diff] [blame] | 235 | For virtual cpus that have been created with S390 user controlled virtual |
| 236 | machines, the resulting vcpu fd can be memory mapped at page offset |
| 237 | KVM_S390_SIE_PAGE_OFFSET in order to obtain a memory map of the virtual |
| 238 | cpu's hardware control block. |
| 239 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 240 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 241 | 4.8 KVM_GET_DIRTY_LOG (vm ioctl) |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 242 | |
| 243 | Capability: basic |
| 244 | Architectures: x86 |
| 245 | Type: vm ioctl |
| 246 | Parameters: struct kvm_dirty_log (in/out) |
| 247 | Returns: 0 on success, -1 on error |
| 248 | |
| 249 | /* for KVM_GET_DIRTY_LOG */ |
| 250 | struct kvm_dirty_log { |
| 251 | __u32 slot; |
| 252 | __u32 padding; |
| 253 | union { |
| 254 | void __user *dirty_bitmap; /* one bit per page */ |
| 255 | __u64 padding; |
| 256 | }; |
| 257 | }; |
| 258 | |
| 259 | Given a memory slot, return a bitmap containing any pages dirtied |
| 260 | since the last call to this ioctl. Bit 0 is the first page in the |
| 261 | memory slot. Ensure the entire structure is cleared to avoid padding |
| 262 | issues. |
| 263 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 264 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 265 | 4.9 KVM_SET_MEMORY_ALIAS |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 266 | |
| 267 | Capability: basic |
| 268 | Architectures: x86 |
| 269 | Type: vm ioctl |
| 270 | Parameters: struct kvm_memory_alias (in) |
| 271 | Returns: 0 (success), -1 (error) |
| 272 | |
Avi Kivity | a1f4d395 | 2010-06-21 11:44:20 +0300 | [diff] [blame] | 273 | This ioctl is obsolete and has been removed. |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 274 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 275 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 276 | 4.10 KVM_RUN |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 277 | |
| 278 | Capability: basic |
| 279 | Architectures: all |
| 280 | Type: vcpu ioctl |
| 281 | Parameters: none |
| 282 | Returns: 0 on success, -1 on error |
| 283 | Errors: |
| 284 | EINTR: an unmasked signal is pending |
| 285 | |
| 286 | This ioctl is used to run a guest virtual cpu. While there are no |
| 287 | explicit parameters, there is an implicit parameter block that can be |
| 288 | obtained by mmap()ing the vcpu fd at offset 0, with the size given by |
| 289 | KVM_GET_VCPU_MMAP_SIZE. The parameter block is formatted as a 'struct |
| 290 | kvm_run' (see below). |
| 291 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 292 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 293 | 4.11 KVM_GET_REGS |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 294 | |
| 295 | Capability: basic |
Christoffer Dall | 749cf76c | 2013-01-20 18:28:06 -0500 | [diff] [blame] | 296 | Architectures: all except ARM |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 297 | Type: vcpu ioctl |
| 298 | Parameters: struct kvm_regs (out) |
| 299 | Returns: 0 on success, -1 on error |
| 300 | |
| 301 | Reads the general purpose registers from the vcpu. |
| 302 | |
| 303 | /* x86 */ |
| 304 | struct kvm_regs { |
| 305 | /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */ |
| 306 | __u64 rax, rbx, rcx, rdx; |
| 307 | __u64 rsi, rdi, rsp, rbp; |
| 308 | __u64 r8, r9, r10, r11; |
| 309 | __u64 r12, r13, r14, r15; |
| 310 | __u64 rip, rflags; |
| 311 | }; |
| 312 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 313 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 314 | 4.12 KVM_SET_REGS |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 315 | |
| 316 | Capability: basic |
Christoffer Dall | 749cf76c | 2013-01-20 18:28:06 -0500 | [diff] [blame] | 317 | Architectures: all except ARM |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 318 | Type: vcpu ioctl |
| 319 | Parameters: struct kvm_regs (in) |
| 320 | Returns: 0 on success, -1 on error |
| 321 | |
| 322 | Writes the general purpose registers into the vcpu. |
| 323 | |
| 324 | See KVM_GET_REGS for the data structure. |
| 325 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 326 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 327 | 4.13 KVM_GET_SREGS |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 328 | |
| 329 | Capability: basic |
Scott Wood | 5ce941e | 2011-04-27 17:24:21 -0500 | [diff] [blame] | 330 | Architectures: x86, ppc |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 331 | Type: vcpu ioctl |
| 332 | Parameters: struct kvm_sregs (out) |
| 333 | Returns: 0 on success, -1 on error |
| 334 | |
| 335 | Reads special registers from the vcpu. |
| 336 | |
| 337 | /* x86 */ |
| 338 | struct kvm_sregs { |
| 339 | struct kvm_segment cs, ds, es, fs, gs, ss; |
| 340 | struct kvm_segment tr, ldt; |
| 341 | struct kvm_dtable gdt, idt; |
| 342 | __u64 cr0, cr2, cr3, cr4, cr8; |
| 343 | __u64 efer; |
| 344 | __u64 apic_base; |
| 345 | __u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64]; |
| 346 | }; |
| 347 | |
Scott Wood | 5ce941e | 2011-04-27 17:24:21 -0500 | [diff] [blame] | 348 | /* ppc -- see arch/powerpc/include/asm/kvm.h */ |
| 349 | |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 350 | interrupt_bitmap is a bitmap of pending external interrupts. At most |
| 351 | one bit may be set. This interrupt has been acknowledged by the APIC |
| 352 | but not yet injected into the cpu core. |
| 353 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 354 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 355 | 4.14 KVM_SET_SREGS |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 356 | |
| 357 | Capability: basic |
Scott Wood | 5ce941e | 2011-04-27 17:24:21 -0500 | [diff] [blame] | 358 | Architectures: x86, ppc |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 359 | Type: vcpu ioctl |
| 360 | Parameters: struct kvm_sregs (in) |
| 361 | Returns: 0 on success, -1 on error |
| 362 | |
| 363 | Writes special registers into the vcpu. See KVM_GET_SREGS for the |
| 364 | data structures. |
| 365 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 366 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 367 | 4.15 KVM_TRANSLATE |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 368 | |
| 369 | Capability: basic |
| 370 | Architectures: x86 |
| 371 | Type: vcpu ioctl |
| 372 | Parameters: struct kvm_translation (in/out) |
| 373 | Returns: 0 on success, -1 on error |
| 374 | |
| 375 | Translates a virtual address according to the vcpu's current address |
| 376 | translation mode. |
| 377 | |
| 378 | struct kvm_translation { |
| 379 | /* in */ |
| 380 | __u64 linear_address; |
| 381 | |
| 382 | /* out */ |
| 383 | __u64 physical_address; |
| 384 | __u8 valid; |
| 385 | __u8 writeable; |
| 386 | __u8 usermode; |
| 387 | __u8 pad[5]; |
| 388 | }; |
| 389 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 390 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 391 | 4.16 KVM_INTERRUPT |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 392 | |
| 393 | Capability: basic |
Alexander Graf | 6f7a2bd | 2010-08-31 02:03:32 +0200 | [diff] [blame] | 394 | Architectures: x86, ppc |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 395 | Type: vcpu ioctl |
| 396 | Parameters: struct kvm_interrupt (in) |
| 397 | Returns: 0 on success, -1 on error |
| 398 | |
| 399 | Queues a hardware interrupt vector to be injected. This is only |
Alexander Graf | 6f7a2bd | 2010-08-31 02:03:32 +0200 | [diff] [blame] | 400 | useful if in-kernel local APIC or equivalent is not used. |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 401 | |
| 402 | /* for KVM_INTERRUPT */ |
| 403 | struct kvm_interrupt { |
| 404 | /* in */ |
| 405 | __u32 irq; |
| 406 | }; |
| 407 | |
Alexander Graf | 6f7a2bd | 2010-08-31 02:03:32 +0200 | [diff] [blame] | 408 | X86: |
| 409 | |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 410 | Note 'irq' is an interrupt vector, not an interrupt pin or line. |
| 411 | |
Alexander Graf | 6f7a2bd | 2010-08-31 02:03:32 +0200 | [diff] [blame] | 412 | PPC: |
| 413 | |
| 414 | Queues an external interrupt to be injected. This ioctl is overleaded |
| 415 | with 3 different irq values: |
| 416 | |
| 417 | a) KVM_INTERRUPT_SET |
| 418 | |
| 419 | This injects an edge type external interrupt into the guest once it's ready |
| 420 | to receive interrupts. When injected, the interrupt is done. |
| 421 | |
| 422 | b) KVM_INTERRUPT_UNSET |
| 423 | |
| 424 | This unsets any pending interrupt. |
| 425 | |
| 426 | Only available with KVM_CAP_PPC_UNSET_IRQ. |
| 427 | |
| 428 | c) KVM_INTERRUPT_SET_LEVEL |
| 429 | |
| 430 | This injects a level type external interrupt into the guest context. The |
| 431 | interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET |
| 432 | is triggered. |
| 433 | |
| 434 | Only available with KVM_CAP_PPC_IRQ_LEVEL. |
| 435 | |
| 436 | Note that any value for 'irq' other than the ones stated above is invalid |
| 437 | and incurs unexpected behavior. |
| 438 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 439 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 440 | 4.17 KVM_DEBUG_GUEST |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 441 | |
| 442 | Capability: basic |
| 443 | Architectures: none |
| 444 | Type: vcpu ioctl |
| 445 | Parameters: none) |
| 446 | Returns: -1 on error |
| 447 | |
| 448 | Support for this has been removed. Use KVM_SET_GUEST_DEBUG instead. |
| 449 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 450 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 451 | 4.18 KVM_GET_MSRS |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 452 | |
| 453 | Capability: basic |
| 454 | Architectures: x86 |
| 455 | Type: vcpu ioctl |
| 456 | Parameters: struct kvm_msrs (in/out) |
| 457 | Returns: 0 on success, -1 on error |
| 458 | |
| 459 | Reads model-specific registers from the vcpu. Supported msr indices can |
| 460 | be obtained using KVM_GET_MSR_INDEX_LIST. |
| 461 | |
| 462 | struct kvm_msrs { |
| 463 | __u32 nmsrs; /* number of msrs in entries */ |
| 464 | __u32 pad; |
| 465 | |
| 466 | struct kvm_msr_entry entries[0]; |
| 467 | }; |
| 468 | |
| 469 | struct kvm_msr_entry { |
| 470 | __u32 index; |
| 471 | __u32 reserved; |
| 472 | __u64 data; |
| 473 | }; |
| 474 | |
| 475 | Application code should set the 'nmsrs' member (which indicates the |
| 476 | size of the entries array) and the 'index' member of each array entry. |
| 477 | kvm will fill in the 'data' member. |
| 478 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 479 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 480 | 4.19 KVM_SET_MSRS |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 481 | |
| 482 | Capability: basic |
| 483 | Architectures: x86 |
| 484 | Type: vcpu ioctl |
| 485 | Parameters: struct kvm_msrs (in) |
| 486 | Returns: 0 on success, -1 on error |
| 487 | |
| 488 | Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the |
| 489 | data structures. |
| 490 | |
| 491 | Application code should set the 'nmsrs' member (which indicates the |
| 492 | size of the entries array), and the 'index' and 'data' members of each |
| 493 | array entry. |
| 494 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 495 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 496 | 4.20 KVM_SET_CPUID |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 497 | |
| 498 | Capability: basic |
| 499 | Architectures: x86 |
| 500 | Type: vcpu ioctl |
| 501 | Parameters: struct kvm_cpuid (in) |
| 502 | Returns: 0 on success, -1 on error |
| 503 | |
| 504 | Defines the vcpu responses to the cpuid instruction. Applications |
| 505 | should use the KVM_SET_CPUID2 ioctl if available. |
| 506 | |
| 507 | |
| 508 | struct kvm_cpuid_entry { |
| 509 | __u32 function; |
| 510 | __u32 eax; |
| 511 | __u32 ebx; |
| 512 | __u32 ecx; |
| 513 | __u32 edx; |
| 514 | __u32 padding; |
| 515 | }; |
| 516 | |
| 517 | /* for KVM_SET_CPUID */ |
| 518 | struct kvm_cpuid { |
| 519 | __u32 nent; |
| 520 | __u32 padding; |
| 521 | struct kvm_cpuid_entry entries[0]; |
| 522 | }; |
| 523 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 524 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 525 | 4.21 KVM_SET_SIGNAL_MASK |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 526 | |
| 527 | Capability: basic |
| 528 | Architectures: x86 |
| 529 | Type: vcpu ioctl |
| 530 | Parameters: struct kvm_signal_mask (in) |
| 531 | Returns: 0 on success, -1 on error |
| 532 | |
| 533 | Defines which signals are blocked during execution of KVM_RUN. This |
| 534 | signal mask temporarily overrides the threads signal mask. Any |
| 535 | unblocked signal received (except SIGKILL and SIGSTOP, which retain |
| 536 | their traditional behaviour) will cause KVM_RUN to return with -EINTR. |
| 537 | |
| 538 | Note the signal will only be delivered if not blocked by the original |
| 539 | signal mask. |
| 540 | |
| 541 | /* for KVM_SET_SIGNAL_MASK */ |
| 542 | struct kvm_signal_mask { |
| 543 | __u32 len; |
| 544 | __u8 sigset[0]; |
| 545 | }; |
| 546 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 547 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 548 | 4.22 KVM_GET_FPU |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 549 | |
| 550 | Capability: basic |
| 551 | Architectures: x86 |
| 552 | Type: vcpu ioctl |
| 553 | Parameters: struct kvm_fpu (out) |
| 554 | Returns: 0 on success, -1 on error |
| 555 | |
| 556 | Reads the floating point state from the vcpu. |
| 557 | |
| 558 | /* for KVM_GET_FPU and KVM_SET_FPU */ |
| 559 | struct kvm_fpu { |
| 560 | __u8 fpr[8][16]; |
| 561 | __u16 fcw; |
| 562 | __u16 fsw; |
| 563 | __u8 ftwx; /* in fxsave format */ |
| 564 | __u8 pad1; |
| 565 | __u16 last_opcode; |
| 566 | __u64 last_ip; |
| 567 | __u64 last_dp; |
| 568 | __u8 xmm[16][16]; |
| 569 | __u32 mxcsr; |
| 570 | __u32 pad2; |
| 571 | }; |
| 572 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 573 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 574 | 4.23 KVM_SET_FPU |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 575 | |
| 576 | Capability: basic |
| 577 | Architectures: x86 |
| 578 | Type: vcpu ioctl |
| 579 | Parameters: struct kvm_fpu (in) |
| 580 | Returns: 0 on success, -1 on error |
| 581 | |
| 582 | Writes the floating point state to the vcpu. |
| 583 | |
| 584 | /* for KVM_GET_FPU and KVM_SET_FPU */ |
| 585 | struct kvm_fpu { |
| 586 | __u8 fpr[8][16]; |
| 587 | __u16 fcw; |
| 588 | __u16 fsw; |
| 589 | __u8 ftwx; /* in fxsave format */ |
| 590 | __u8 pad1; |
| 591 | __u16 last_opcode; |
| 592 | __u64 last_ip; |
| 593 | __u64 last_dp; |
| 594 | __u8 xmm[16][16]; |
| 595 | __u32 mxcsr; |
| 596 | __u32 pad2; |
| 597 | }; |
| 598 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 599 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 600 | 4.24 KVM_CREATE_IRQCHIP |
Avi Kivity | 5dadbfd | 2009-08-23 17:08:04 +0300 | [diff] [blame] | 601 | |
| 602 | Capability: KVM_CAP_IRQCHIP |
Christoffer Dall | 749cf76c | 2013-01-20 18:28:06 -0500 | [diff] [blame] | 603 | Architectures: x86, ia64, ARM |
Avi Kivity | 5dadbfd | 2009-08-23 17:08:04 +0300 | [diff] [blame] | 604 | Type: vm ioctl |
| 605 | Parameters: none |
| 606 | Returns: 0 on success, -1 on error |
| 607 | |
| 608 | Creates an interrupt controller model in the kernel. On x86, creates a virtual |
| 609 | ioapic, a virtual PIC (two PICs, nested), and sets up future vcpus to have a |
| 610 | local APIC. IRQ routing for GSIs 0-15 is set to both PIC and IOAPIC; GSI 16-23 |
Christoffer Dall | 749cf76c | 2013-01-20 18:28:06 -0500 | [diff] [blame] | 611 | only go to the IOAPIC. On ia64, a IOSAPIC is created. On ARM, a GIC is |
| 612 | created. |
Avi Kivity | 5dadbfd | 2009-08-23 17:08:04 +0300 | [diff] [blame] | 613 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 614 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 615 | 4.25 KVM_IRQ_LINE |
Avi Kivity | 5dadbfd | 2009-08-23 17:08:04 +0300 | [diff] [blame] | 616 | |
| 617 | Capability: KVM_CAP_IRQCHIP |
Christoffer Dall | 86ce8535 | 2013-01-20 18:28:08 -0500 | [diff] [blame] | 618 | Architectures: x86, ia64, arm |
Avi Kivity | 5dadbfd | 2009-08-23 17:08:04 +0300 | [diff] [blame] | 619 | Type: vm ioctl |
| 620 | Parameters: struct kvm_irq_level |
| 621 | Returns: 0 on success, -1 on error |
| 622 | |
| 623 | Sets the level of a GSI input to the interrupt controller model in the kernel. |
Christoffer Dall | 86ce8535 | 2013-01-20 18:28:08 -0500 | [diff] [blame] | 624 | On some architectures it is required that an interrupt controller model has |
| 625 | been previously created with KVM_CREATE_IRQCHIP. Note that edge-triggered |
| 626 | interrupts require the level to be set to 1 and then back to 0. |
| 627 | |
| 628 | ARM can signal an interrupt either at the CPU level, or at the in-kernel irqchip |
| 629 | (GIC), and for in-kernel irqchip can tell the GIC to use PPIs designated for |
| 630 | specific cpus. The irq field is interpreted like this: |
| 631 | |
| 632 | Â bits: | 31 ... 24 | 23 ... 16 | 15 ... 0 | |
| 633 | field: | irq_type | vcpu_index | irq_id | |
| 634 | |
| 635 | The irq_type field has the following values: |
| 636 | - irq_type[0]: out-of-kernel GIC: irq_id 0 is IRQ, irq_id 1 is FIQ |
| 637 | - irq_type[1]: in-kernel GIC: SPI, irq_id between 32 and 1019 (incl.) |
| 638 | (the vcpu_index field is ignored) |
| 639 | - irq_type[2]: in-kernel GIC: PPI, irq_id between 16 and 31 (incl.) |
| 640 | |
| 641 | (The irq_id field thus corresponds nicely to the IRQ ID in the ARM GIC specs) |
| 642 | |
| 643 | In both cases, level is used to raise/lower the line. |
Avi Kivity | 5dadbfd | 2009-08-23 17:08:04 +0300 | [diff] [blame] | 644 | |
| 645 | struct kvm_irq_level { |
| 646 | union { |
| 647 | __u32 irq; /* GSI */ |
| 648 | __s32 status; /* not used for KVM_IRQ_LEVEL */ |
| 649 | }; |
| 650 | __u32 level; /* 0 or 1 */ |
| 651 | }; |
| 652 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 653 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 654 | 4.26 KVM_GET_IRQCHIP |
Avi Kivity | 5dadbfd | 2009-08-23 17:08:04 +0300 | [diff] [blame] | 655 | |
| 656 | Capability: KVM_CAP_IRQCHIP |
| 657 | Architectures: x86, ia64 |
| 658 | Type: vm ioctl |
| 659 | Parameters: struct kvm_irqchip (in/out) |
| 660 | Returns: 0 on success, -1 on error |
| 661 | |
| 662 | Reads the state of a kernel interrupt controller created with |
| 663 | KVM_CREATE_IRQCHIP into a buffer provided by the caller. |
| 664 | |
| 665 | struct kvm_irqchip { |
| 666 | __u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */ |
| 667 | __u32 pad; |
| 668 | union { |
| 669 | char dummy[512]; /* reserving space */ |
| 670 | struct kvm_pic_state pic; |
| 671 | struct kvm_ioapic_state ioapic; |
| 672 | } chip; |
| 673 | }; |
| 674 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 675 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 676 | 4.27 KVM_SET_IRQCHIP |
Avi Kivity | 5dadbfd | 2009-08-23 17:08:04 +0300 | [diff] [blame] | 677 | |
| 678 | Capability: KVM_CAP_IRQCHIP |
| 679 | Architectures: x86, ia64 |
| 680 | Type: vm ioctl |
| 681 | Parameters: struct kvm_irqchip (in) |
| 682 | Returns: 0 on success, -1 on error |
| 683 | |
| 684 | Sets the state of a kernel interrupt controller created with |
| 685 | KVM_CREATE_IRQCHIP from a buffer provided by the caller. |
| 686 | |
| 687 | struct kvm_irqchip { |
| 688 | __u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */ |
| 689 | __u32 pad; |
| 690 | union { |
| 691 | char dummy[512]; /* reserving space */ |
| 692 | struct kvm_pic_state pic; |
| 693 | struct kvm_ioapic_state ioapic; |
| 694 | } chip; |
| 695 | }; |
| 696 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 697 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 698 | 4.28 KVM_XEN_HVM_CONFIG |
Ed Swierk | ffde22a | 2009-10-15 15:21:43 -0700 | [diff] [blame] | 699 | |
| 700 | Capability: KVM_CAP_XEN_HVM |
| 701 | Architectures: x86 |
| 702 | Type: vm ioctl |
| 703 | Parameters: struct kvm_xen_hvm_config (in) |
| 704 | Returns: 0 on success, -1 on error |
| 705 | |
| 706 | Sets the MSR that the Xen HVM guest uses to initialize its hypercall |
| 707 | page, and provides the starting address and size of the hypercall |
| 708 | blobs in userspace. When the guest writes the MSR, kvm copies one |
| 709 | page of a blob (32- or 64-bit, depending on the vcpu mode) to guest |
| 710 | memory. |
| 711 | |
| 712 | struct kvm_xen_hvm_config { |
| 713 | __u32 flags; |
| 714 | __u32 msr; |
| 715 | __u64 blob_addr_32; |
| 716 | __u64 blob_addr_64; |
| 717 | __u8 blob_size_32; |
| 718 | __u8 blob_size_64; |
| 719 | __u8 pad2[30]; |
| 720 | }; |
| 721 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 722 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 723 | 4.29 KVM_GET_CLOCK |
Glauber Costa | afbcf7a | 2009-10-16 15:28:36 -0400 | [diff] [blame] | 724 | |
| 725 | Capability: KVM_CAP_ADJUST_CLOCK |
| 726 | Architectures: x86 |
| 727 | Type: vm ioctl |
| 728 | Parameters: struct kvm_clock_data (out) |
| 729 | Returns: 0 on success, -1 on error |
| 730 | |
| 731 | Gets the current timestamp of kvmclock as seen by the current guest. In |
| 732 | conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios |
| 733 | such as migration. |
| 734 | |
| 735 | struct kvm_clock_data { |
| 736 | __u64 clock; /* kvmclock current value */ |
| 737 | __u32 flags; |
| 738 | __u32 pad[9]; |
| 739 | }; |
| 740 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 741 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 742 | 4.30 KVM_SET_CLOCK |
Glauber Costa | afbcf7a | 2009-10-16 15:28:36 -0400 | [diff] [blame] | 743 | |
| 744 | Capability: KVM_CAP_ADJUST_CLOCK |
| 745 | Architectures: x86 |
| 746 | Type: vm ioctl |
| 747 | Parameters: struct kvm_clock_data (in) |
| 748 | Returns: 0 on success, -1 on error |
| 749 | |
Wu Fengguang | 2044892d | 2009-12-24 09:04:16 +0800 | [diff] [blame] | 750 | Sets the current timestamp of kvmclock to the value specified in its parameter. |
Glauber Costa | afbcf7a | 2009-10-16 15:28:36 -0400 | [diff] [blame] | 751 | In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenarios |
| 752 | such as migration. |
| 753 | |
| 754 | struct kvm_clock_data { |
| 755 | __u64 clock; /* kvmclock current value */ |
| 756 | __u32 flags; |
| 757 | __u32 pad[9]; |
| 758 | }; |
| 759 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 760 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 761 | 4.31 KVM_GET_VCPU_EVENTS |
Jan Kiszka | 3cfc309 | 2009-11-12 01:04:25 +0100 | [diff] [blame] | 762 | |
| 763 | Capability: KVM_CAP_VCPU_EVENTS |
Jan Kiszka | 48005f6 | 2010-02-19 19:38:07 +0100 | [diff] [blame] | 764 | Extended by: KVM_CAP_INTR_SHADOW |
Jan Kiszka | 3cfc309 | 2009-11-12 01:04:25 +0100 | [diff] [blame] | 765 | Architectures: x86 |
| 766 | Type: vm ioctl |
| 767 | Parameters: struct kvm_vcpu_event (out) |
| 768 | Returns: 0 on success, -1 on error |
| 769 | |
| 770 | Gets currently pending exceptions, interrupts, and NMIs as well as related |
| 771 | states of the vcpu. |
| 772 | |
| 773 | struct kvm_vcpu_events { |
| 774 | struct { |
| 775 | __u8 injected; |
| 776 | __u8 nr; |
| 777 | __u8 has_error_code; |
| 778 | __u8 pad; |
| 779 | __u32 error_code; |
| 780 | } exception; |
| 781 | struct { |
| 782 | __u8 injected; |
| 783 | __u8 nr; |
| 784 | __u8 soft; |
Jan Kiszka | 48005f6 | 2010-02-19 19:38:07 +0100 | [diff] [blame] | 785 | __u8 shadow; |
Jan Kiszka | 3cfc309 | 2009-11-12 01:04:25 +0100 | [diff] [blame] | 786 | } interrupt; |
| 787 | struct { |
| 788 | __u8 injected; |
| 789 | __u8 pending; |
| 790 | __u8 masked; |
| 791 | __u8 pad; |
| 792 | } nmi; |
| 793 | __u32 sipi_vector; |
Jan Kiszka | dab4b91 | 2009-12-06 18:24:15 +0100 | [diff] [blame] | 794 | __u32 flags; |
Jan Kiszka | 3cfc309 | 2009-11-12 01:04:25 +0100 | [diff] [blame] | 795 | }; |
| 796 | |
Jan Kiszka | 48005f6 | 2010-02-19 19:38:07 +0100 | [diff] [blame] | 797 | KVM_VCPUEVENT_VALID_SHADOW may be set in the flags field to signal that |
| 798 | interrupt.shadow contains a valid state. Otherwise, this field is undefined. |
| 799 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 800 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 801 | 4.32 KVM_SET_VCPU_EVENTS |
Jan Kiszka | 3cfc309 | 2009-11-12 01:04:25 +0100 | [diff] [blame] | 802 | |
| 803 | Capability: KVM_CAP_VCPU_EVENTS |
Jan Kiszka | 48005f6 | 2010-02-19 19:38:07 +0100 | [diff] [blame] | 804 | Extended by: KVM_CAP_INTR_SHADOW |
Jan Kiszka | 3cfc309 | 2009-11-12 01:04:25 +0100 | [diff] [blame] | 805 | Architectures: x86 |
| 806 | Type: vm ioctl |
| 807 | Parameters: struct kvm_vcpu_event (in) |
| 808 | Returns: 0 on success, -1 on error |
| 809 | |
| 810 | Set pending exceptions, interrupts, and NMIs as well as related states of the |
| 811 | vcpu. |
| 812 | |
| 813 | See KVM_GET_VCPU_EVENTS for the data structure. |
| 814 | |
Jan Kiszka | dab4b91 | 2009-12-06 18:24:15 +0100 | [diff] [blame] | 815 | Fields that may be modified asynchronously by running VCPUs can be excluded |
| 816 | from the update. These fields are nmi.pending and sipi_vector. Keep the |
| 817 | corresponding bits in the flags field cleared to suppress overwriting the |
| 818 | current in-kernel state. The bits are: |
| 819 | |
| 820 | KVM_VCPUEVENT_VALID_NMI_PENDING - transfer nmi.pending to the kernel |
| 821 | KVM_VCPUEVENT_VALID_SIPI_VECTOR - transfer sipi_vector |
| 822 | |
Jan Kiszka | 48005f6 | 2010-02-19 19:38:07 +0100 | [diff] [blame] | 823 | If KVM_CAP_INTR_SHADOW is available, KVM_VCPUEVENT_VALID_SHADOW can be set in |
| 824 | the flags field to signal that interrupt.shadow contains a valid state and |
| 825 | shall be written into the VCPU. |
| 826 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 827 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 828 | 4.33 KVM_GET_DEBUGREGS |
Jan Kiszka | a1efbe7 | 2010-02-15 10:45:43 +0100 | [diff] [blame] | 829 | |
| 830 | Capability: KVM_CAP_DEBUGREGS |
| 831 | Architectures: x86 |
| 832 | Type: vm ioctl |
| 833 | Parameters: struct kvm_debugregs (out) |
| 834 | Returns: 0 on success, -1 on error |
| 835 | |
| 836 | Reads debug registers from the vcpu. |
| 837 | |
| 838 | struct kvm_debugregs { |
| 839 | __u64 db[4]; |
| 840 | __u64 dr6; |
| 841 | __u64 dr7; |
| 842 | __u64 flags; |
| 843 | __u64 reserved[9]; |
| 844 | }; |
| 845 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 846 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 847 | 4.34 KVM_SET_DEBUGREGS |
Jan Kiszka | a1efbe7 | 2010-02-15 10:45:43 +0100 | [diff] [blame] | 848 | |
| 849 | Capability: KVM_CAP_DEBUGREGS |
| 850 | Architectures: x86 |
| 851 | Type: vm ioctl |
| 852 | Parameters: struct kvm_debugregs (in) |
| 853 | Returns: 0 on success, -1 on error |
| 854 | |
| 855 | Writes debug registers into the vcpu. |
| 856 | |
| 857 | See KVM_GET_DEBUGREGS for the data structure. The flags field is unused |
| 858 | yet and must be cleared on entry. |
| 859 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 860 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 861 | 4.35 KVM_SET_USER_MEMORY_REGION |
Avi Kivity | 0f2d8f4 | 2010-03-25 12:16:48 +0200 | [diff] [blame] | 862 | |
| 863 | Capability: KVM_CAP_USER_MEM |
| 864 | Architectures: all |
| 865 | Type: vm ioctl |
| 866 | Parameters: struct kvm_userspace_memory_region (in) |
| 867 | Returns: 0 on success, -1 on error |
| 868 | |
| 869 | struct kvm_userspace_memory_region { |
| 870 | __u32 slot; |
| 871 | __u32 flags; |
| 872 | __u64 guest_phys_addr; |
| 873 | __u64 memory_size; /* bytes */ |
| 874 | __u64 userspace_addr; /* start of the userspace allocated memory */ |
| 875 | }; |
| 876 | |
| 877 | /* for kvm_memory_region::flags */ |
Xiao Guangrong | 4d8b81a | 2012-08-21 11:02:51 +0800 | [diff] [blame] | 878 | #define KVM_MEM_LOG_DIRTY_PAGES (1UL << 0) |
| 879 | #define KVM_MEM_READONLY (1UL << 1) |
Avi Kivity | 0f2d8f4 | 2010-03-25 12:16:48 +0200 | [diff] [blame] | 880 | |
| 881 | This ioctl allows the user to create or modify a guest physical memory |
| 882 | slot. When changing an existing slot, it may be moved in the guest |
| 883 | physical memory space, or its flags may be modified. It may not be |
| 884 | resized. Slots may not overlap in guest physical address space. |
| 885 | |
| 886 | Memory for the region is taken starting at the address denoted by the |
| 887 | field userspace_addr, which must point at user addressable memory for |
| 888 | the entire memory slot size. Any object may back this memory, including |
| 889 | anonymous memory, ordinary files, and hugetlbfs. |
| 890 | |
| 891 | It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr |
| 892 | be identical. This allows large pages in the guest to be backed by large |
| 893 | pages in the host. |
| 894 | |
Jan Kiszka | 7efd8fa | 2012-09-07 13:17:47 +0200 | [diff] [blame] | 895 | The flags field supports two flag, KVM_MEM_LOG_DIRTY_PAGES, which instructs |
| 896 | kvm to keep track of writes to memory within the slot. See KVM_GET_DIRTY_LOG |
| 897 | ioctl. The KVM_CAP_READONLY_MEM capability indicates the availability of the |
| 898 | KVM_MEM_READONLY flag. When this flag is set for a memory region, KVM only |
| 899 | allows read accesses. Writes will be posted to userspace as KVM_EXIT_MMIO |
| 900 | exits. |
Avi Kivity | 0f2d8f4 | 2010-03-25 12:16:48 +0200 | [diff] [blame] | 901 | |
Jan Kiszka | 7efd8fa | 2012-09-07 13:17:47 +0200 | [diff] [blame] | 902 | When the KVM_CAP_SYNC_MMU capability is available, changes in the backing of |
| 903 | the memory region are automatically reflected into the guest. For example, an |
| 904 | mmap() that affects the region will be made visible immediately. Another |
| 905 | example is madvise(MADV_DROP). |
Avi Kivity | 0f2d8f4 | 2010-03-25 12:16:48 +0200 | [diff] [blame] | 906 | |
| 907 | It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl. |
| 908 | The KVM_SET_MEMORY_REGION does not allow fine grained control over memory |
| 909 | allocation and is deprecated. |
Jan Kiszka | 3cfc309 | 2009-11-12 01:04:25 +0100 | [diff] [blame] | 910 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 911 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 912 | 4.36 KVM_SET_TSS_ADDR |
Avi Kivity | 8a5416d | 2010-03-25 12:27:30 +0200 | [diff] [blame] | 913 | |
| 914 | Capability: KVM_CAP_SET_TSS_ADDR |
| 915 | Architectures: x86 |
| 916 | Type: vm ioctl |
| 917 | Parameters: unsigned long tss_address (in) |
| 918 | Returns: 0 on success, -1 on error |
| 919 | |
| 920 | This ioctl defines the physical address of a three-page region in the guest |
| 921 | physical address space. The region must be within the first 4GB of the |
| 922 | guest physical address space and must not conflict with any memory slot |
| 923 | or any mmio address. The guest may malfunction if it accesses this memory |
| 924 | region. |
| 925 | |
| 926 | This ioctl is required on Intel-based hosts. This is needed on Intel hardware |
| 927 | because of a quirk in the virtualization implementation (see the internals |
| 928 | documentation when it pops into existence). |
| 929 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 930 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 931 | 4.37 KVM_ENABLE_CAP |
Alexander Graf | 71fbfd5 | 2010-03-24 21:48:29 +0100 | [diff] [blame] | 932 | |
| 933 | Capability: KVM_CAP_ENABLE_CAP |
| 934 | Architectures: ppc |
| 935 | Type: vcpu ioctl |
| 936 | Parameters: struct kvm_enable_cap (in) |
| 937 | Returns: 0 on success; -1 on error |
| 938 | |
| 939 | +Not all extensions are enabled by default. Using this ioctl the application |
| 940 | can enable an extension, making it available to the guest. |
| 941 | |
| 942 | On systems that do not support this ioctl, it always fails. On systems that |
| 943 | do support it, it only works for extensions that are supported for enablement. |
| 944 | |
| 945 | To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should |
| 946 | be used. |
| 947 | |
| 948 | struct kvm_enable_cap { |
| 949 | /* in */ |
| 950 | __u32 cap; |
| 951 | |
| 952 | The capability that is supposed to get enabled. |
| 953 | |
| 954 | __u32 flags; |
| 955 | |
| 956 | A bitfield indicating future enhancements. Has to be 0 for now. |
| 957 | |
| 958 | __u64 args[4]; |
| 959 | |
| 960 | Arguments for enabling a feature. If a feature needs initial values to |
| 961 | function properly, this is the place to put them. |
| 962 | |
| 963 | __u8 pad[64]; |
| 964 | }; |
| 965 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 966 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 967 | 4.38 KVM_GET_MP_STATE |
Avi Kivity | b843f06 | 2010-04-25 15:51:46 +0300 | [diff] [blame] | 968 | |
| 969 | Capability: KVM_CAP_MP_STATE |
| 970 | Architectures: x86, ia64 |
| 971 | Type: vcpu ioctl |
| 972 | Parameters: struct kvm_mp_state (out) |
| 973 | Returns: 0 on success; -1 on error |
| 974 | |
| 975 | struct kvm_mp_state { |
| 976 | __u32 mp_state; |
| 977 | }; |
| 978 | |
| 979 | Returns the vcpu's current "multiprocessing state" (though also valid on |
| 980 | uniprocessor guests). |
| 981 | |
| 982 | Possible values are: |
| 983 | |
| 984 | - KVM_MP_STATE_RUNNABLE: the vcpu is currently running |
| 985 | - KVM_MP_STATE_UNINITIALIZED: the vcpu is an application processor (AP) |
| 986 | which has not yet received an INIT signal |
| 987 | - KVM_MP_STATE_INIT_RECEIVED: the vcpu has received an INIT signal, and is |
| 988 | now ready for a SIPI |
| 989 | - KVM_MP_STATE_HALTED: the vcpu has executed a HLT instruction and |
| 990 | is waiting for an interrupt |
| 991 | - KVM_MP_STATE_SIPI_RECEIVED: the vcpu has just received a SIPI (vector |
Uwe Kleine-König | b595076 | 2010-11-01 15:38:34 -0400 | [diff] [blame] | 992 | accessible via KVM_GET_VCPU_EVENTS) |
Avi Kivity | b843f06 | 2010-04-25 15:51:46 +0300 | [diff] [blame] | 993 | |
| 994 | This ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel |
| 995 | irqchip, the multiprocessing state must be maintained by userspace. |
| 996 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 997 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 998 | 4.39 KVM_SET_MP_STATE |
Avi Kivity | b843f06 | 2010-04-25 15:51:46 +0300 | [diff] [blame] | 999 | |
| 1000 | Capability: KVM_CAP_MP_STATE |
| 1001 | Architectures: x86, ia64 |
| 1002 | Type: vcpu ioctl |
| 1003 | Parameters: struct kvm_mp_state (in) |
| 1004 | Returns: 0 on success; -1 on error |
| 1005 | |
| 1006 | Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for |
| 1007 | arguments. |
| 1008 | |
| 1009 | This ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel |
| 1010 | irqchip, the multiprocessing state must be maintained by userspace. |
| 1011 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1012 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 1013 | 4.40 KVM_SET_IDENTITY_MAP_ADDR |
Avi Kivity | 47dbb84 | 2010-04-29 12:08:56 +0300 | [diff] [blame] | 1014 | |
| 1015 | Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR |
| 1016 | Architectures: x86 |
| 1017 | Type: vm ioctl |
| 1018 | Parameters: unsigned long identity (in) |
| 1019 | Returns: 0 on success, -1 on error |
| 1020 | |
| 1021 | This ioctl defines the physical address of a one-page region in the guest |
| 1022 | physical address space. The region must be within the first 4GB of the |
| 1023 | guest physical address space and must not conflict with any memory slot |
| 1024 | or any mmio address. The guest may malfunction if it accesses this memory |
| 1025 | region. |
| 1026 | |
| 1027 | This ioctl is required on Intel-based hosts. This is needed on Intel hardware |
| 1028 | because of a quirk in the virtualization implementation (see the internals |
| 1029 | documentation when it pops into existence). |
| 1030 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1031 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 1032 | 4.41 KVM_SET_BOOT_CPU_ID |
Avi Kivity | 57bc24c | 2010-04-29 12:12:57 +0300 | [diff] [blame] | 1033 | |
| 1034 | Capability: KVM_CAP_SET_BOOT_CPU_ID |
| 1035 | Architectures: x86, ia64 |
| 1036 | Type: vm ioctl |
| 1037 | Parameters: unsigned long vcpu_id |
| 1038 | Returns: 0 on success, -1 on error |
| 1039 | |
| 1040 | Define which vcpu is the Bootstrap Processor (BSP). Values are the same |
| 1041 | as the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the default |
| 1042 | is vcpu 0. |
| 1043 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1044 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 1045 | 4.42 KVM_GET_XSAVE |
Sheng Yang | 2d5b5a6 | 2010-06-13 17:29:39 +0800 | [diff] [blame] | 1046 | |
| 1047 | Capability: KVM_CAP_XSAVE |
| 1048 | Architectures: x86 |
| 1049 | Type: vcpu ioctl |
| 1050 | Parameters: struct kvm_xsave (out) |
| 1051 | Returns: 0 on success, -1 on error |
| 1052 | |
| 1053 | struct kvm_xsave { |
| 1054 | __u32 region[1024]; |
| 1055 | }; |
| 1056 | |
| 1057 | This ioctl would copy current vcpu's xsave struct to the userspace. |
| 1058 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1059 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 1060 | 4.43 KVM_SET_XSAVE |
Sheng Yang | 2d5b5a6 | 2010-06-13 17:29:39 +0800 | [diff] [blame] | 1061 | |
| 1062 | Capability: KVM_CAP_XSAVE |
| 1063 | Architectures: x86 |
| 1064 | Type: vcpu ioctl |
| 1065 | Parameters: struct kvm_xsave (in) |
| 1066 | Returns: 0 on success, -1 on error |
| 1067 | |
| 1068 | struct kvm_xsave { |
| 1069 | __u32 region[1024]; |
| 1070 | }; |
| 1071 | |
| 1072 | This ioctl would copy userspace's xsave struct to the kernel. |
| 1073 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1074 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 1075 | 4.44 KVM_GET_XCRS |
Sheng Yang | 2d5b5a6 | 2010-06-13 17:29:39 +0800 | [diff] [blame] | 1076 | |
| 1077 | Capability: KVM_CAP_XCRS |
| 1078 | Architectures: x86 |
| 1079 | Type: vcpu ioctl |
| 1080 | Parameters: struct kvm_xcrs (out) |
| 1081 | Returns: 0 on success, -1 on error |
| 1082 | |
| 1083 | struct kvm_xcr { |
| 1084 | __u32 xcr; |
| 1085 | __u32 reserved; |
| 1086 | __u64 value; |
| 1087 | }; |
| 1088 | |
| 1089 | struct kvm_xcrs { |
| 1090 | __u32 nr_xcrs; |
| 1091 | __u32 flags; |
| 1092 | struct kvm_xcr xcrs[KVM_MAX_XCRS]; |
| 1093 | __u64 padding[16]; |
| 1094 | }; |
| 1095 | |
| 1096 | This ioctl would copy current vcpu's xcrs to the userspace. |
| 1097 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1098 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 1099 | 4.45 KVM_SET_XCRS |
Sheng Yang | 2d5b5a6 | 2010-06-13 17:29:39 +0800 | [diff] [blame] | 1100 | |
| 1101 | Capability: KVM_CAP_XCRS |
| 1102 | Architectures: x86 |
| 1103 | Type: vcpu ioctl |
| 1104 | Parameters: struct kvm_xcrs (in) |
| 1105 | Returns: 0 on success, -1 on error |
| 1106 | |
| 1107 | struct kvm_xcr { |
| 1108 | __u32 xcr; |
| 1109 | __u32 reserved; |
| 1110 | __u64 value; |
| 1111 | }; |
| 1112 | |
| 1113 | struct kvm_xcrs { |
| 1114 | __u32 nr_xcrs; |
| 1115 | __u32 flags; |
| 1116 | struct kvm_xcr xcrs[KVM_MAX_XCRS]; |
| 1117 | __u64 padding[16]; |
| 1118 | }; |
| 1119 | |
| 1120 | This ioctl would set vcpu's xcr to the value userspace specified. |
| 1121 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1122 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 1123 | 4.46 KVM_GET_SUPPORTED_CPUID |
Avi Kivity | d153513 | 2010-07-14 09:45:21 +0300 | [diff] [blame] | 1124 | |
| 1125 | Capability: KVM_CAP_EXT_CPUID |
| 1126 | Architectures: x86 |
| 1127 | Type: system ioctl |
| 1128 | Parameters: struct kvm_cpuid2 (in/out) |
| 1129 | Returns: 0 on success, -1 on error |
| 1130 | |
| 1131 | struct kvm_cpuid2 { |
| 1132 | __u32 nent; |
| 1133 | __u32 padding; |
| 1134 | struct kvm_cpuid_entry2 entries[0]; |
| 1135 | }; |
| 1136 | |
| 1137 | #define KVM_CPUID_FLAG_SIGNIFCANT_INDEX 1 |
| 1138 | #define KVM_CPUID_FLAG_STATEFUL_FUNC 2 |
| 1139 | #define KVM_CPUID_FLAG_STATE_READ_NEXT 4 |
| 1140 | |
| 1141 | struct kvm_cpuid_entry2 { |
| 1142 | __u32 function; |
| 1143 | __u32 index; |
| 1144 | __u32 flags; |
| 1145 | __u32 eax; |
| 1146 | __u32 ebx; |
| 1147 | __u32 ecx; |
| 1148 | __u32 edx; |
| 1149 | __u32 padding[3]; |
| 1150 | }; |
| 1151 | |
| 1152 | This ioctl returns x86 cpuid features which are supported by both the hardware |
| 1153 | and kvm. Userspace can use the information returned by this ioctl to |
| 1154 | construct cpuid information (for KVM_SET_CPUID2) that is consistent with |
| 1155 | hardware, kernel, and userspace capabilities, and with user requirements (for |
| 1156 | example, the user may wish to constrain cpuid to emulate older hardware, |
| 1157 | or for feature consistency across a cluster). |
| 1158 | |
| 1159 | Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structure |
| 1160 | with the 'nent' field indicating the number of entries in the variable-size |
| 1161 | array 'entries'. If the number of entries is too low to describe the cpu |
| 1162 | capabilities, an error (E2BIG) is returned. If the number is too high, |
| 1163 | the 'nent' field is adjusted and an error (ENOMEM) is returned. If the |
| 1164 | number is just right, the 'nent' field is adjusted to the number of valid |
| 1165 | entries in the 'entries' array, which is then filled. |
| 1166 | |
| 1167 | The entries returned are the host cpuid as returned by the cpuid instruction, |
Avi Kivity | c39cbd2 | 2010-09-12 16:39:11 +0200 | [diff] [blame] | 1168 | with unknown or unsupported features masked out. Some features (for example, |
| 1169 | x2apic), may not be present in the host cpu, but are exposed by kvm if it can |
| 1170 | emulate them efficiently. The fields in each entry are defined as follows: |
Avi Kivity | d153513 | 2010-07-14 09:45:21 +0300 | [diff] [blame] | 1171 | |
| 1172 | function: the eax value used to obtain the entry |
| 1173 | index: the ecx value used to obtain the entry (for entries that are |
| 1174 | affected by ecx) |
| 1175 | flags: an OR of zero or more of the following: |
| 1176 | KVM_CPUID_FLAG_SIGNIFCANT_INDEX: |
| 1177 | if the index field is valid |
| 1178 | KVM_CPUID_FLAG_STATEFUL_FUNC: |
| 1179 | if cpuid for this function returns different values for successive |
| 1180 | invocations; there will be several entries with the same function, |
| 1181 | all with this flag set |
| 1182 | KVM_CPUID_FLAG_STATE_READ_NEXT: |
| 1183 | for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is |
| 1184 | the first entry to be read by a cpu |
| 1185 | eax, ebx, ecx, edx: the values returned by the cpuid instruction for |
| 1186 | this function/index combination |
| 1187 | |
Jan Kiszka | 4d25a066 | 2011-12-21 12:28:29 +0100 | [diff] [blame] | 1188 | The TSC deadline timer feature (CPUID leaf 1, ecx[24]) is always returned |
| 1189 | as false, since the feature depends on KVM_CREATE_IRQCHIP for local APIC |
| 1190 | support. Instead it is reported via |
| 1191 | |
| 1192 | ioctl(KVM_CHECK_EXTENSION, KVM_CAP_TSC_DEADLINE_TIMER) |
| 1193 | |
| 1194 | if that returns true and you use KVM_CREATE_IRQCHIP, or if you emulate the |
| 1195 | feature in userspace, then you can enable the feature for KVM_SET_CPUID2. |
| 1196 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1197 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 1198 | 4.47 KVM_PPC_GET_PVINFO |
Alexander Graf | 15711e9 | 2010-07-29 14:48:08 +0200 | [diff] [blame] | 1199 | |
| 1200 | Capability: KVM_CAP_PPC_GET_PVINFO |
| 1201 | Architectures: ppc |
| 1202 | Type: vm ioctl |
| 1203 | Parameters: struct kvm_ppc_pvinfo (out) |
| 1204 | Returns: 0 on success, !0 on error |
| 1205 | |
| 1206 | struct kvm_ppc_pvinfo { |
| 1207 | __u32 flags; |
| 1208 | __u32 hcall[4]; |
| 1209 | __u8 pad[108]; |
| 1210 | }; |
| 1211 | |
| 1212 | This ioctl fetches PV specific information that need to be passed to the guest |
| 1213 | using the device tree or other means from vm context. |
| 1214 | |
Liu Yu-B13201 | 9202e07 | 2012-07-03 05:48:52 +0000 | [diff] [blame] | 1215 | The hcall array defines 4 instructions that make up a hypercall. |
Alexander Graf | 15711e9 | 2010-07-29 14:48:08 +0200 | [diff] [blame] | 1216 | |
| 1217 | If any additional field gets added to this structure later on, a bit for that |
| 1218 | additional piece of information will be set in the flags bitmap. |
| 1219 | |
Liu Yu-B13201 | 9202e07 | 2012-07-03 05:48:52 +0000 | [diff] [blame] | 1220 | The flags bitmap is defined as: |
| 1221 | |
| 1222 | /* the host supports the ePAPR idle hcall |
| 1223 | #define KVM_PPC_PVINFO_FLAGS_EV_IDLE (1<<0) |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1224 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 1225 | 4.48 KVM_ASSIGN_PCI_DEVICE |
Jan Kiszka | 49f4817 | 2010-11-16 22:30:07 +0100 | [diff] [blame] | 1226 | |
| 1227 | Capability: KVM_CAP_DEVICE_ASSIGNMENT |
| 1228 | Architectures: x86 ia64 |
| 1229 | Type: vm ioctl |
| 1230 | Parameters: struct kvm_assigned_pci_dev (in) |
| 1231 | Returns: 0 on success, -1 on error |
| 1232 | |
| 1233 | Assigns a host PCI device to the VM. |
| 1234 | |
| 1235 | struct kvm_assigned_pci_dev { |
| 1236 | __u32 assigned_dev_id; |
| 1237 | __u32 busnr; |
| 1238 | __u32 devfn; |
| 1239 | __u32 flags; |
| 1240 | __u32 segnr; |
| 1241 | union { |
| 1242 | __u32 reserved[11]; |
| 1243 | }; |
| 1244 | }; |
| 1245 | |
| 1246 | The PCI device is specified by the triple segnr, busnr, and devfn. |
| 1247 | Identification in succeeding service requests is done via assigned_dev_id. The |
| 1248 | following flags are specified: |
| 1249 | |
| 1250 | /* Depends on KVM_CAP_IOMMU */ |
| 1251 | #define KVM_DEV_ASSIGN_ENABLE_IOMMU (1 << 0) |
Jan Kiszka | 07700a9 | 2012-02-28 14:19:54 +0100 | [diff] [blame] | 1252 | /* The following two depend on KVM_CAP_PCI_2_3 */ |
| 1253 | #define KVM_DEV_ASSIGN_PCI_2_3 (1 << 1) |
| 1254 | #define KVM_DEV_ASSIGN_MASK_INTX (1 << 2) |
| 1255 | |
| 1256 | If KVM_DEV_ASSIGN_PCI_2_3 is set, the kernel will manage legacy INTx interrupts |
| 1257 | via the PCI-2.3-compliant device-level mask, thus enable IRQ sharing with other |
| 1258 | assigned devices or host devices. KVM_DEV_ASSIGN_MASK_INTX specifies the |
| 1259 | guest's view on the INTx mask, see KVM_ASSIGN_SET_INTX_MASK for details. |
Jan Kiszka | 49f4817 | 2010-11-16 22:30:07 +0100 | [diff] [blame] | 1260 | |
Alex Williamson | 4238737 | 2011-12-20 21:59:03 -0700 | [diff] [blame] | 1261 | The KVM_DEV_ASSIGN_ENABLE_IOMMU flag is a mandatory option to ensure |
| 1262 | isolation of the device. Usages not specifying this flag are deprecated. |
| 1263 | |
Alex Williamson | 3d27e23 | 2011-12-20 21:59:09 -0700 | [diff] [blame] | 1264 | Only PCI header type 0 devices with PCI BAR resources are supported by |
| 1265 | device assignment. The user requesting this ioctl must have read/write |
| 1266 | access to the PCI sysfs resource files associated with the device. |
| 1267 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1268 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 1269 | 4.49 KVM_DEASSIGN_PCI_DEVICE |
Jan Kiszka | 49f4817 | 2010-11-16 22:30:07 +0100 | [diff] [blame] | 1270 | |
| 1271 | Capability: KVM_CAP_DEVICE_DEASSIGNMENT |
| 1272 | Architectures: x86 ia64 |
| 1273 | Type: vm ioctl |
| 1274 | Parameters: struct kvm_assigned_pci_dev (in) |
| 1275 | Returns: 0 on success, -1 on error |
| 1276 | |
| 1277 | Ends PCI device assignment, releasing all associated resources. |
| 1278 | |
| 1279 | See KVM_CAP_DEVICE_ASSIGNMENT for the data structure. Only assigned_dev_id is |
| 1280 | used in kvm_assigned_pci_dev to identify the device. |
| 1281 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1282 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 1283 | 4.50 KVM_ASSIGN_DEV_IRQ |
Jan Kiszka | 49f4817 | 2010-11-16 22:30:07 +0100 | [diff] [blame] | 1284 | |
| 1285 | Capability: KVM_CAP_ASSIGN_DEV_IRQ |
| 1286 | Architectures: x86 ia64 |
| 1287 | Type: vm ioctl |
| 1288 | Parameters: struct kvm_assigned_irq (in) |
| 1289 | Returns: 0 on success, -1 on error |
| 1290 | |
| 1291 | Assigns an IRQ to a passed-through device. |
| 1292 | |
| 1293 | struct kvm_assigned_irq { |
| 1294 | __u32 assigned_dev_id; |
Jan Kiszka | 91e3d71 | 2011-06-03 08:51:05 +0200 | [diff] [blame] | 1295 | __u32 host_irq; /* ignored (legacy field) */ |
Jan Kiszka | 49f4817 | 2010-11-16 22:30:07 +0100 | [diff] [blame] | 1296 | __u32 guest_irq; |
| 1297 | __u32 flags; |
| 1298 | union { |
Jan Kiszka | 49f4817 | 2010-11-16 22:30:07 +0100 | [diff] [blame] | 1299 | __u32 reserved[12]; |
| 1300 | }; |
| 1301 | }; |
| 1302 | |
| 1303 | The following flags are defined: |
| 1304 | |
| 1305 | #define KVM_DEV_IRQ_HOST_INTX (1 << 0) |
| 1306 | #define KVM_DEV_IRQ_HOST_MSI (1 << 1) |
| 1307 | #define KVM_DEV_IRQ_HOST_MSIX (1 << 2) |
| 1308 | |
| 1309 | #define KVM_DEV_IRQ_GUEST_INTX (1 << 8) |
| 1310 | #define KVM_DEV_IRQ_GUEST_MSI (1 << 9) |
| 1311 | #define KVM_DEV_IRQ_GUEST_MSIX (1 << 10) |
| 1312 | |
| 1313 | It is not valid to specify multiple types per host or guest IRQ. However, the |
| 1314 | IRQ type of host and guest can differ or can even be null. |
| 1315 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1316 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 1317 | 4.51 KVM_DEASSIGN_DEV_IRQ |
Jan Kiszka | 49f4817 | 2010-11-16 22:30:07 +0100 | [diff] [blame] | 1318 | |
| 1319 | Capability: KVM_CAP_ASSIGN_DEV_IRQ |
| 1320 | Architectures: x86 ia64 |
| 1321 | Type: vm ioctl |
| 1322 | Parameters: struct kvm_assigned_irq (in) |
| 1323 | Returns: 0 on success, -1 on error |
| 1324 | |
| 1325 | Ends an IRQ assignment to a passed-through device. |
| 1326 | |
| 1327 | See KVM_ASSIGN_DEV_IRQ for the data structure. The target device is specified |
| 1328 | by assigned_dev_id, flags must correspond to the IRQ type specified on |
| 1329 | KVM_ASSIGN_DEV_IRQ. Partial deassignment of host or guest IRQ is allowed. |
| 1330 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1331 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 1332 | 4.52 KVM_SET_GSI_ROUTING |
Jan Kiszka | 49f4817 | 2010-11-16 22:30:07 +0100 | [diff] [blame] | 1333 | |
| 1334 | Capability: KVM_CAP_IRQ_ROUTING |
| 1335 | Architectures: x86 ia64 |
| 1336 | Type: vm ioctl |
| 1337 | Parameters: struct kvm_irq_routing (in) |
| 1338 | Returns: 0 on success, -1 on error |
| 1339 | |
| 1340 | Sets the GSI routing table entries, overwriting any previously set entries. |
| 1341 | |
| 1342 | struct kvm_irq_routing { |
| 1343 | __u32 nr; |
| 1344 | __u32 flags; |
| 1345 | struct kvm_irq_routing_entry entries[0]; |
| 1346 | }; |
| 1347 | |
| 1348 | No flags are specified so far, the corresponding field must be set to zero. |
| 1349 | |
| 1350 | struct kvm_irq_routing_entry { |
| 1351 | __u32 gsi; |
| 1352 | __u32 type; |
| 1353 | __u32 flags; |
| 1354 | __u32 pad; |
| 1355 | union { |
| 1356 | struct kvm_irq_routing_irqchip irqchip; |
| 1357 | struct kvm_irq_routing_msi msi; |
| 1358 | __u32 pad[8]; |
| 1359 | } u; |
| 1360 | }; |
| 1361 | |
| 1362 | /* gsi routing entry types */ |
| 1363 | #define KVM_IRQ_ROUTING_IRQCHIP 1 |
| 1364 | #define KVM_IRQ_ROUTING_MSI 2 |
| 1365 | |
| 1366 | No flags are specified so far, the corresponding field must be set to zero. |
| 1367 | |
| 1368 | struct kvm_irq_routing_irqchip { |
| 1369 | __u32 irqchip; |
| 1370 | __u32 pin; |
| 1371 | }; |
| 1372 | |
| 1373 | struct kvm_irq_routing_msi { |
| 1374 | __u32 address_lo; |
| 1375 | __u32 address_hi; |
| 1376 | __u32 data; |
| 1377 | __u32 pad; |
| 1378 | }; |
| 1379 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1380 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 1381 | 4.53 KVM_ASSIGN_SET_MSIX_NR |
Jan Kiszka | 49f4817 | 2010-11-16 22:30:07 +0100 | [diff] [blame] | 1382 | |
| 1383 | Capability: KVM_CAP_DEVICE_MSIX |
| 1384 | Architectures: x86 ia64 |
| 1385 | Type: vm ioctl |
| 1386 | Parameters: struct kvm_assigned_msix_nr (in) |
| 1387 | Returns: 0 on success, -1 on error |
| 1388 | |
Jan Kiszka | 58f0964 | 2011-06-11 12:24:24 +0200 | [diff] [blame] | 1389 | Set the number of MSI-X interrupts for an assigned device. The number is |
| 1390 | reset again by terminating the MSI-X assignment of the device via |
| 1391 | KVM_DEASSIGN_DEV_IRQ. Calling this service more than once at any earlier |
| 1392 | point will fail. |
Jan Kiszka | 49f4817 | 2010-11-16 22:30:07 +0100 | [diff] [blame] | 1393 | |
| 1394 | struct kvm_assigned_msix_nr { |
| 1395 | __u32 assigned_dev_id; |
| 1396 | __u16 entry_nr; |
| 1397 | __u16 padding; |
| 1398 | }; |
| 1399 | |
| 1400 | #define KVM_MAX_MSIX_PER_DEV 256 |
| 1401 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1402 | |
Paul Bolle | 68ba697 | 2011-02-15 00:05:59 +0100 | [diff] [blame] | 1403 | 4.54 KVM_ASSIGN_SET_MSIX_ENTRY |
Jan Kiszka | 49f4817 | 2010-11-16 22:30:07 +0100 | [diff] [blame] | 1404 | |
| 1405 | Capability: KVM_CAP_DEVICE_MSIX |
| 1406 | Architectures: x86 ia64 |
| 1407 | Type: vm ioctl |
| 1408 | Parameters: struct kvm_assigned_msix_entry (in) |
| 1409 | Returns: 0 on success, -1 on error |
| 1410 | |
| 1411 | Specifies the routing of an MSI-X assigned device interrupt to a GSI. Setting |
| 1412 | the GSI vector to zero means disabling the interrupt. |
| 1413 | |
| 1414 | struct kvm_assigned_msix_entry { |
| 1415 | __u32 assigned_dev_id; |
| 1416 | __u32 gsi; |
| 1417 | __u16 entry; /* The index of entry in the MSI-X table */ |
| 1418 | __u16 padding[3]; |
| 1419 | }; |
| 1420 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1421 | |
| 1422 | 4.55 KVM_SET_TSC_KHZ |
Joerg Roedel | 92a1f12 | 2011-03-25 09:44:51 +0100 | [diff] [blame] | 1423 | |
| 1424 | Capability: KVM_CAP_TSC_CONTROL |
| 1425 | Architectures: x86 |
| 1426 | Type: vcpu ioctl |
| 1427 | Parameters: virtual tsc_khz |
| 1428 | Returns: 0 on success, -1 on error |
| 1429 | |
| 1430 | Specifies the tsc frequency for the virtual machine. The unit of the |
| 1431 | frequency is KHz. |
| 1432 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1433 | |
| 1434 | 4.56 KVM_GET_TSC_KHZ |
Joerg Roedel | 92a1f12 | 2011-03-25 09:44:51 +0100 | [diff] [blame] | 1435 | |
| 1436 | Capability: KVM_CAP_GET_TSC_KHZ |
| 1437 | Architectures: x86 |
| 1438 | Type: vcpu ioctl |
| 1439 | Parameters: none |
| 1440 | Returns: virtual tsc-khz on success, negative value on error |
| 1441 | |
| 1442 | Returns the tsc frequency of the guest. The unit of the return value is |
| 1443 | KHz. If the host has unstable tsc this ioctl returns -EIO instead as an |
| 1444 | error. |
| 1445 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1446 | |
| 1447 | 4.57 KVM_GET_LAPIC |
Avi Kivity | e767793 | 2011-05-11 08:30:51 -0400 | [diff] [blame] | 1448 | |
| 1449 | Capability: KVM_CAP_IRQCHIP |
| 1450 | Architectures: x86 |
| 1451 | Type: vcpu ioctl |
| 1452 | Parameters: struct kvm_lapic_state (out) |
| 1453 | Returns: 0 on success, -1 on error |
| 1454 | |
| 1455 | #define KVM_APIC_REG_SIZE 0x400 |
| 1456 | struct kvm_lapic_state { |
| 1457 | char regs[KVM_APIC_REG_SIZE]; |
| 1458 | }; |
| 1459 | |
| 1460 | Reads the Local APIC registers and copies them into the input argument. The |
| 1461 | data format and layout are the same as documented in the architecture manual. |
| 1462 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1463 | |
| 1464 | 4.58 KVM_SET_LAPIC |
Avi Kivity | e767793 | 2011-05-11 08:30:51 -0400 | [diff] [blame] | 1465 | |
| 1466 | Capability: KVM_CAP_IRQCHIP |
| 1467 | Architectures: x86 |
| 1468 | Type: vcpu ioctl |
| 1469 | Parameters: struct kvm_lapic_state (in) |
| 1470 | Returns: 0 on success, -1 on error |
| 1471 | |
| 1472 | #define KVM_APIC_REG_SIZE 0x400 |
| 1473 | struct kvm_lapic_state { |
| 1474 | char regs[KVM_APIC_REG_SIZE]; |
| 1475 | }; |
| 1476 | |
| 1477 | Copies the input argument into the the Local APIC registers. The data format |
| 1478 | and layout are the same as documented in the architecture manual. |
| 1479 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1480 | |
| 1481 | 4.59 KVM_IOEVENTFD |
Sasha Levin | 55399a0 | 2011-05-28 14:12:30 +0300 | [diff] [blame] | 1482 | |
| 1483 | Capability: KVM_CAP_IOEVENTFD |
| 1484 | Architectures: all |
| 1485 | Type: vm ioctl |
| 1486 | Parameters: struct kvm_ioeventfd (in) |
| 1487 | Returns: 0 on success, !0 on error |
| 1488 | |
| 1489 | This ioctl attaches or detaches an ioeventfd to a legal pio/mmio address |
| 1490 | within the guest. A guest write in the registered address will signal the |
| 1491 | provided event instead of triggering an exit. |
| 1492 | |
| 1493 | struct kvm_ioeventfd { |
| 1494 | __u64 datamatch; |
| 1495 | __u64 addr; /* legal pio/mmio address */ |
| 1496 | __u32 len; /* 1, 2, 4, or 8 bytes */ |
| 1497 | __s32 fd; |
| 1498 | __u32 flags; |
| 1499 | __u8 pad[36]; |
| 1500 | }; |
| 1501 | |
| 1502 | The following flags are defined: |
| 1503 | |
| 1504 | #define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch) |
| 1505 | #define KVM_IOEVENTFD_FLAG_PIO (1 << kvm_ioeventfd_flag_nr_pio) |
| 1506 | #define KVM_IOEVENTFD_FLAG_DEASSIGN (1 << kvm_ioeventfd_flag_nr_deassign) |
| 1507 | |
| 1508 | If datamatch flag is set, the event will be signaled only if the written value |
| 1509 | to the registered address is equal to datamatch in struct kvm_ioeventfd. |
| 1510 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1511 | |
| 1512 | 4.60 KVM_DIRTY_TLB |
Scott Wood | dc83b8b | 2011-08-18 15:25:21 -0500 | [diff] [blame] | 1513 | |
| 1514 | Capability: KVM_CAP_SW_TLB |
| 1515 | Architectures: ppc |
| 1516 | Type: vcpu ioctl |
| 1517 | Parameters: struct kvm_dirty_tlb (in) |
| 1518 | Returns: 0 on success, -1 on error |
| 1519 | |
| 1520 | struct kvm_dirty_tlb { |
| 1521 | __u64 bitmap; |
| 1522 | __u32 num_dirty; |
| 1523 | }; |
| 1524 | |
| 1525 | This must be called whenever userspace has changed an entry in the shared |
| 1526 | TLB, prior to calling KVM_RUN on the associated vcpu. |
| 1527 | |
| 1528 | The "bitmap" field is the userspace address of an array. This array |
| 1529 | consists of a number of bits, equal to the total number of TLB entries as |
| 1530 | determined by the last successful call to KVM_CONFIG_TLB, rounded up to the |
| 1531 | nearest multiple of 64. |
| 1532 | |
| 1533 | Each bit corresponds to one TLB entry, ordered the same as in the shared TLB |
| 1534 | array. |
| 1535 | |
| 1536 | The array is little-endian: the bit 0 is the least significant bit of the |
| 1537 | first byte, bit 8 is the least significant bit of the second byte, etc. |
| 1538 | This avoids any complications with differing word sizes. |
| 1539 | |
| 1540 | The "num_dirty" field is a performance hint for KVM to determine whether it |
| 1541 | should skip processing the bitmap and just invalidate everything. It must |
| 1542 | be set to the number of set bits in the bitmap. |
| 1543 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1544 | |
| 1545 | 4.61 KVM_ASSIGN_SET_INTX_MASK |
Jan Kiszka | 07700a9 | 2012-02-28 14:19:54 +0100 | [diff] [blame] | 1546 | |
| 1547 | Capability: KVM_CAP_PCI_2_3 |
| 1548 | Architectures: x86 |
| 1549 | Type: vm ioctl |
| 1550 | Parameters: struct kvm_assigned_pci_dev (in) |
| 1551 | Returns: 0 on success, -1 on error |
| 1552 | |
| 1553 | Allows userspace to mask PCI INTx interrupts from the assigned device. The |
| 1554 | kernel will not deliver INTx interrupts to the guest between setting and |
| 1555 | clearing of KVM_ASSIGN_SET_INTX_MASK via this interface. This enables use of |
| 1556 | and emulation of PCI 2.3 INTx disable command register behavior. |
| 1557 | |
| 1558 | This may be used for both PCI 2.3 devices supporting INTx disable natively and |
| 1559 | older devices lacking this support. Userspace is responsible for emulating the |
| 1560 | read value of the INTx disable bit in the guest visible PCI command register. |
| 1561 | When modifying the INTx disable state, userspace should precede updating the |
| 1562 | physical device command register by calling this ioctl to inform the kernel of |
| 1563 | the new intended INTx mask state. |
| 1564 | |
| 1565 | Note that the kernel uses the device INTx disable bit to internally manage the |
| 1566 | device interrupt state for PCI 2.3 devices. Reads of this register may |
| 1567 | therefore not match the expected value. Writes should always use the guest |
| 1568 | intended INTx disable value rather than attempting to read-copy-update the |
| 1569 | current physical device state. Races between user and kernel updates to the |
| 1570 | INTx disable bit are handled lazily in the kernel. It's possible the device |
| 1571 | may generate unintended interrupts, but they will not be injected into the |
| 1572 | guest. |
| 1573 | |
| 1574 | See KVM_ASSIGN_DEV_IRQ for the data structure. The target device is specified |
| 1575 | by assigned_dev_id. In the flags field, only KVM_DEV_ASSIGN_MASK_INTX is |
| 1576 | evaluated. |
| 1577 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1578 | |
David Gibson | 54738c0 | 2011-06-29 00:22:41 +0000 | [diff] [blame] | 1579 | 4.62 KVM_CREATE_SPAPR_TCE |
| 1580 | |
| 1581 | Capability: KVM_CAP_SPAPR_TCE |
| 1582 | Architectures: powerpc |
| 1583 | Type: vm ioctl |
| 1584 | Parameters: struct kvm_create_spapr_tce (in) |
| 1585 | Returns: file descriptor for manipulating the created TCE table |
| 1586 | |
| 1587 | This creates a virtual TCE (translation control entry) table, which |
| 1588 | is an IOMMU for PAPR-style virtual I/O. It is used to translate |
| 1589 | logical addresses used in virtual I/O into guest physical addresses, |
| 1590 | and provides a scatter/gather capability for PAPR virtual I/O. |
| 1591 | |
| 1592 | /* for KVM_CAP_SPAPR_TCE */ |
| 1593 | struct kvm_create_spapr_tce { |
| 1594 | __u64 liobn; |
| 1595 | __u32 window_size; |
| 1596 | }; |
| 1597 | |
| 1598 | The liobn field gives the logical IO bus number for which to create a |
| 1599 | TCE table. The window_size field specifies the size of the DMA window |
| 1600 | which this TCE table will translate - the table will contain one 64 |
| 1601 | bit TCE entry for every 4kiB of the DMA window. |
| 1602 | |
| 1603 | When the guest issues an H_PUT_TCE hcall on a liobn for which a TCE |
| 1604 | table has been created using this ioctl(), the kernel will handle it |
| 1605 | in real mode, updating the TCE table. H_PUT_TCE calls for other |
| 1606 | liobns will cause a vm exit and must be handled by userspace. |
| 1607 | |
| 1608 | The return value is a file descriptor which can be passed to mmap(2) |
| 1609 | to map the created TCE table into userspace. This lets userspace read |
| 1610 | the entries written by kernel-handled H_PUT_TCE calls, and also lets |
| 1611 | userspace update the TCE table directly which is useful in some |
| 1612 | circumstances. |
| 1613 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1614 | |
Paul Mackerras | aa04b4c | 2011-06-29 00:25:44 +0000 | [diff] [blame] | 1615 | 4.63 KVM_ALLOCATE_RMA |
| 1616 | |
| 1617 | Capability: KVM_CAP_PPC_RMA |
| 1618 | Architectures: powerpc |
| 1619 | Type: vm ioctl |
| 1620 | Parameters: struct kvm_allocate_rma (out) |
| 1621 | Returns: file descriptor for mapping the allocated RMA |
| 1622 | |
| 1623 | This allocates a Real Mode Area (RMA) from the pool allocated at boot |
| 1624 | time by the kernel. An RMA is a physically-contiguous, aligned region |
| 1625 | of memory used on older POWER processors to provide the memory which |
| 1626 | will be accessed by real-mode (MMU off) accesses in a KVM guest. |
| 1627 | POWER processors support a set of sizes for the RMA that usually |
| 1628 | includes 64MB, 128MB, 256MB and some larger powers of two. |
| 1629 | |
| 1630 | /* for KVM_ALLOCATE_RMA */ |
| 1631 | struct kvm_allocate_rma { |
| 1632 | __u64 rma_size; |
| 1633 | }; |
| 1634 | |
| 1635 | The return value is a file descriptor which can be passed to mmap(2) |
| 1636 | to map the allocated RMA into userspace. The mapped area can then be |
| 1637 | passed to the KVM_SET_USER_MEMORY_REGION ioctl to establish it as the |
| 1638 | RMA for a virtual machine. The size of the RMA in bytes (which is |
| 1639 | fixed at host kernel boot time) is returned in the rma_size field of |
| 1640 | the argument structure. |
| 1641 | |
| 1642 | The KVM_CAP_PPC_RMA capability is 1 or 2 if the KVM_ALLOCATE_RMA ioctl |
| 1643 | is supported; 2 if the processor requires all virtual machines to have |
| 1644 | an RMA, or 1 if the processor can use an RMA but doesn't require it, |
| 1645 | because it supports the Virtual RMA (VRMA) facility. |
| 1646 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1647 | |
Avi Kivity | 3f745f1 | 2011-12-07 12:42:47 +0200 | [diff] [blame] | 1648 | 4.64 KVM_NMI |
| 1649 | |
| 1650 | Capability: KVM_CAP_USER_NMI |
| 1651 | Architectures: x86 |
| 1652 | Type: vcpu ioctl |
| 1653 | Parameters: none |
| 1654 | Returns: 0 on success, -1 on error |
| 1655 | |
| 1656 | Queues an NMI on the thread's vcpu. Note this is well defined only |
| 1657 | when KVM_CREATE_IRQCHIP has not been called, since this is an interface |
| 1658 | between the virtual cpu core and virtual local APIC. After KVM_CREATE_IRQCHIP |
| 1659 | has been called, this interface is completely emulated within the kernel. |
| 1660 | |
| 1661 | To use this to emulate the LINT1 input with KVM_CREATE_IRQCHIP, use the |
| 1662 | following algorithm: |
| 1663 | |
| 1664 | - pause the vpcu |
| 1665 | - read the local APIC's state (KVM_GET_LAPIC) |
| 1666 | - check whether changing LINT1 will queue an NMI (see the LVT entry for LINT1) |
| 1667 | - if so, issue KVM_NMI |
| 1668 | - resume the vcpu |
| 1669 | |
| 1670 | Some guests configure the LINT1 NMI input to cause a panic, aiding in |
| 1671 | debugging. |
| 1672 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1673 | |
Alexander Graf | e24ed81 | 2011-09-14 10:02:41 +0200 | [diff] [blame] | 1674 | 4.65 KVM_S390_UCAS_MAP |
Carsten Otte | 27e0393 | 2012-01-04 10:25:21 +0100 | [diff] [blame] | 1675 | |
| 1676 | Capability: KVM_CAP_S390_UCONTROL |
| 1677 | Architectures: s390 |
| 1678 | Type: vcpu ioctl |
| 1679 | Parameters: struct kvm_s390_ucas_mapping (in) |
| 1680 | Returns: 0 in case of success |
| 1681 | |
| 1682 | The parameter is defined like this: |
| 1683 | struct kvm_s390_ucas_mapping { |
| 1684 | __u64 user_addr; |
| 1685 | __u64 vcpu_addr; |
| 1686 | __u64 length; |
| 1687 | }; |
| 1688 | |
| 1689 | This ioctl maps the memory at "user_addr" with the length "length" to |
| 1690 | the vcpu's address space starting at "vcpu_addr". All parameters need to |
| 1691 | be alligned by 1 megabyte. |
| 1692 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1693 | |
Alexander Graf | e24ed81 | 2011-09-14 10:02:41 +0200 | [diff] [blame] | 1694 | 4.66 KVM_S390_UCAS_UNMAP |
Carsten Otte | 27e0393 | 2012-01-04 10:25:21 +0100 | [diff] [blame] | 1695 | |
| 1696 | Capability: KVM_CAP_S390_UCONTROL |
| 1697 | Architectures: s390 |
| 1698 | Type: vcpu ioctl |
| 1699 | Parameters: struct kvm_s390_ucas_mapping (in) |
| 1700 | Returns: 0 in case of success |
| 1701 | |
| 1702 | The parameter is defined like this: |
| 1703 | struct kvm_s390_ucas_mapping { |
| 1704 | __u64 user_addr; |
| 1705 | __u64 vcpu_addr; |
| 1706 | __u64 length; |
| 1707 | }; |
| 1708 | |
| 1709 | This ioctl unmaps the memory in the vcpu's address space starting at |
| 1710 | "vcpu_addr" with the length "length". The field "user_addr" is ignored. |
| 1711 | All parameters need to be alligned by 1 megabyte. |
| 1712 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1713 | |
Alexander Graf | e24ed81 | 2011-09-14 10:02:41 +0200 | [diff] [blame] | 1714 | 4.67 KVM_S390_VCPU_FAULT |
Carsten Otte | ccc7910 | 2012-01-04 10:25:26 +0100 | [diff] [blame] | 1715 | |
| 1716 | Capability: KVM_CAP_S390_UCONTROL |
| 1717 | Architectures: s390 |
| 1718 | Type: vcpu ioctl |
| 1719 | Parameters: vcpu absolute address (in) |
| 1720 | Returns: 0 in case of success |
| 1721 | |
| 1722 | This call creates a page table entry on the virtual cpu's address space |
| 1723 | (for user controlled virtual machines) or the virtual machine's address |
| 1724 | space (for regular virtual machines). This only works for minor faults, |
| 1725 | thus it's recommended to access subject memory page via the user page |
| 1726 | table upfront. This is useful to handle validity intercepts for user |
| 1727 | controlled virtual machines to fault in the virtual cpu's lowcore pages |
| 1728 | prior to calling the KVM_RUN ioctl. |
| 1729 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1730 | |
Alexander Graf | e24ed81 | 2011-09-14 10:02:41 +0200 | [diff] [blame] | 1731 | 4.68 KVM_SET_ONE_REG |
| 1732 | |
| 1733 | Capability: KVM_CAP_ONE_REG |
| 1734 | Architectures: all |
| 1735 | Type: vcpu ioctl |
| 1736 | Parameters: struct kvm_one_reg (in) |
| 1737 | Returns: 0 on success, negative value on failure |
| 1738 | |
| 1739 | struct kvm_one_reg { |
| 1740 | __u64 id; |
| 1741 | __u64 addr; |
| 1742 | }; |
| 1743 | |
| 1744 | Using this ioctl, a single vcpu register can be set to a specific value |
| 1745 | defined by user space with the passed in struct kvm_one_reg, where id |
| 1746 | refers to the register identifier as described below and addr is a pointer |
| 1747 | to a variable with the respective size. There can be architecture agnostic |
| 1748 | and architecture specific registers. Each have their own range of operation |
| 1749 | and their own constants and width. To keep track of the implemented |
| 1750 | registers, find a list below: |
| 1751 | |
| 1752 | Arch | Register | Width (bits) |
| 1753 | | | |
Alexander Graf | 1022fc3 | 2011-09-14 21:45:23 +0200 | [diff] [blame] | 1754 | PPC | KVM_REG_PPC_HIOR | 64 |
Bharat Bhushan | 2e23270 | 2012-08-15 17:37:13 +0000 | [diff] [blame] | 1755 | PPC | KVM_REG_PPC_IAC1 | 64 |
| 1756 | PPC | KVM_REG_PPC_IAC2 | 64 |
| 1757 | PPC | KVM_REG_PPC_IAC3 | 64 |
| 1758 | PPC | KVM_REG_PPC_IAC4 | 64 |
| 1759 | PPC | KVM_REG_PPC_DAC1 | 64 |
| 1760 | PPC | KVM_REG_PPC_DAC2 | 64 |
Paul Mackerras | a136a8b | 2012-09-25 20:31:56 +0000 | [diff] [blame] | 1761 | PPC | KVM_REG_PPC_DABR | 64 |
| 1762 | PPC | KVM_REG_PPC_DSCR | 64 |
| 1763 | PPC | KVM_REG_PPC_PURR | 64 |
| 1764 | PPC | KVM_REG_PPC_SPURR | 64 |
| 1765 | PPC | KVM_REG_PPC_DAR | 64 |
| 1766 | PPC | KVM_REG_PPC_DSISR | 32 |
| 1767 | PPC | KVM_REG_PPC_AMR | 64 |
| 1768 | PPC | KVM_REG_PPC_UAMOR | 64 |
| 1769 | PPC | KVM_REG_PPC_MMCR0 | 64 |
| 1770 | PPC | KVM_REG_PPC_MMCR1 | 64 |
| 1771 | PPC | KVM_REG_PPC_MMCRA | 64 |
| 1772 | PPC | KVM_REG_PPC_PMC1 | 32 |
| 1773 | PPC | KVM_REG_PPC_PMC2 | 32 |
| 1774 | PPC | KVM_REG_PPC_PMC3 | 32 |
| 1775 | PPC | KVM_REG_PPC_PMC4 | 32 |
| 1776 | PPC | KVM_REG_PPC_PMC5 | 32 |
| 1777 | PPC | KVM_REG_PPC_PMC6 | 32 |
| 1778 | PPC | KVM_REG_PPC_PMC7 | 32 |
| 1779 | PPC | KVM_REG_PPC_PMC8 | 32 |
Paul Mackerras | a8bd19e | 2012-09-25 20:32:30 +0000 | [diff] [blame] | 1780 | PPC | KVM_REG_PPC_FPR0 | 64 |
| 1781 | ... |
| 1782 | PPC | KVM_REG_PPC_FPR31 | 64 |
| 1783 | PPC | KVM_REG_PPC_VR0 | 128 |
| 1784 | ... |
| 1785 | PPC | KVM_REG_PPC_VR31 | 128 |
| 1786 | PPC | KVM_REG_PPC_VSR0 | 128 |
| 1787 | ... |
| 1788 | PPC | KVM_REG_PPC_VSR31 | 128 |
| 1789 | PPC | KVM_REG_PPC_FPSCR | 64 |
| 1790 | PPC | KVM_REG_PPC_VSCR | 32 |
Paul Mackerras | 55b665b | 2012-09-25 20:33:06 +0000 | [diff] [blame] | 1791 | PPC | KVM_REG_PPC_VPA_ADDR | 64 |
| 1792 | PPC | KVM_REG_PPC_VPA_SLB | 128 |
| 1793 | PPC | KVM_REG_PPC_VPA_DTL | 128 |
Mihai Caraman | 352df1d | 2012-10-11 06:13:29 +0000 | [diff] [blame] | 1794 | PPC | KVM_REG_PPC_EPCR | 32 |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1795 | |
Christoffer Dall | 749cf76c | 2013-01-20 18:28:06 -0500 | [diff] [blame] | 1796 | ARM registers are mapped using the lower 32 bits. The upper 16 of that |
| 1797 | is the register group type, or coprocessor number: |
| 1798 | |
| 1799 | ARM core registers have the following id bit patterns: |
| 1800 | 0x4002 0000 0010 <index into the kvm_regs struct:16> |
| 1801 | |
Christoffer Dall | 1138245 | 2013-01-20 18:28:10 -0500 | [diff] [blame] | 1802 | ARM 32-bit CP15 registers have the following id bit patterns: |
| 1803 | 0x4002 0000 000F <zero:1> <crn:4> <crm:4> <opc1:4> <opc2:3> |
| 1804 | |
| 1805 | ARM 64-bit CP15 registers have the following id bit patterns: |
| 1806 | 0x4003 0000 000F <zero:1> <zero:4> <crm:4> <opc1:4> <zero:3> |
Christoffer Dall | 749cf76c | 2013-01-20 18:28:06 -0500 | [diff] [blame] | 1807 | |
Christoffer Dall | c27581e | 2013-01-20 18:28:10 -0500 | [diff] [blame] | 1808 | ARM CCSIDR registers are demultiplexed by CSSELR value: |
| 1809 | 0x4002 0000 0011 00 <csselr:8> |
Christoffer Dall | 749cf76c | 2013-01-20 18:28:06 -0500 | [diff] [blame] | 1810 | |
Rusty Russell | 4fe21e4 | 2013-01-20 18:28:11 -0500 | [diff] [blame] | 1811 | ARM 32-bit VFP control registers have the following id bit patterns: |
| 1812 | 0x4002 0000 0012 1 <regno:12> |
| 1813 | |
| 1814 | ARM 64-bit FP registers have the following id bit patterns: |
| 1815 | 0x4002 0000 0012 0 <regno:12> |
| 1816 | |
Alexander Graf | e24ed81 | 2011-09-14 10:02:41 +0200 | [diff] [blame] | 1817 | 4.69 KVM_GET_ONE_REG |
| 1818 | |
| 1819 | Capability: KVM_CAP_ONE_REG |
| 1820 | Architectures: all |
| 1821 | Type: vcpu ioctl |
| 1822 | Parameters: struct kvm_one_reg (in and out) |
| 1823 | Returns: 0 on success, negative value on failure |
| 1824 | |
| 1825 | This ioctl allows to receive the value of a single register implemented |
| 1826 | in a vcpu. The register to read is indicated by the "id" field of the |
| 1827 | kvm_one_reg struct passed in. On success, the register value can be found |
| 1828 | at the memory location pointed to by "addr". |
| 1829 | |
| 1830 | The list of registers accessible using this interface is identical to the |
Bharat Bhushan | 2e23270 | 2012-08-15 17:37:13 +0000 | [diff] [blame] | 1831 | list in 4.68. |
Alexander Graf | e24ed81 | 2011-09-14 10:02:41 +0200 | [diff] [blame] | 1832 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1833 | |
Eric B Munson | 1c0b28c | 2012-03-10 14:37:27 -0500 | [diff] [blame] | 1834 | 4.70 KVM_KVMCLOCK_CTRL |
| 1835 | |
| 1836 | Capability: KVM_CAP_KVMCLOCK_CTRL |
| 1837 | Architectures: Any that implement pvclocks (currently x86 only) |
| 1838 | Type: vcpu ioctl |
| 1839 | Parameters: None |
| 1840 | Returns: 0 on success, -1 on error |
| 1841 | |
| 1842 | This signals to the host kernel that the specified guest is being paused by |
| 1843 | userspace. The host will set a flag in the pvclock structure that is checked |
| 1844 | from the soft lockup watchdog. The flag is part of the pvclock structure that |
| 1845 | is shared between guest and host, specifically the second bit of the flags |
| 1846 | field of the pvclock_vcpu_time_info structure. It will be set exclusively by |
| 1847 | the host and read/cleared exclusively by the guest. The guest operation of |
| 1848 | checking and clearing the flag must an atomic operation so |
| 1849 | load-link/store-conditional, or equivalent must be used. There are two cases |
| 1850 | where the guest will clear the flag: when the soft lockup watchdog timer resets |
| 1851 | itself or when a soft lockup is detected. This ioctl can be called any time |
| 1852 | after pausing the vcpu, but before it is resumed. |
| 1853 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1854 | |
Jan Kiszka | 07975ad | 2012-03-29 21:14:12 +0200 | [diff] [blame] | 1855 | 4.71 KVM_SIGNAL_MSI |
| 1856 | |
| 1857 | Capability: KVM_CAP_SIGNAL_MSI |
| 1858 | Architectures: x86 |
| 1859 | Type: vm ioctl |
| 1860 | Parameters: struct kvm_msi (in) |
| 1861 | Returns: >0 on delivery, 0 if guest blocked the MSI, and -1 on error |
| 1862 | |
| 1863 | Directly inject a MSI message. Only valid with in-kernel irqchip that handles |
| 1864 | MSI messages. |
| 1865 | |
| 1866 | struct kvm_msi { |
| 1867 | __u32 address_lo; |
| 1868 | __u32 address_hi; |
| 1869 | __u32 data; |
| 1870 | __u32 flags; |
| 1871 | __u8 pad[16]; |
| 1872 | }; |
| 1873 | |
| 1874 | No flags are defined so far. The corresponding field must be 0. |
| 1875 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 1876 | |
Jan Kiszka | 0589ff6 | 2012-04-24 16:40:16 +0200 | [diff] [blame] | 1877 | 4.71 KVM_CREATE_PIT2 |
| 1878 | |
| 1879 | Capability: KVM_CAP_PIT2 |
| 1880 | Architectures: x86 |
| 1881 | Type: vm ioctl |
| 1882 | Parameters: struct kvm_pit_config (in) |
| 1883 | Returns: 0 on success, -1 on error |
| 1884 | |
| 1885 | Creates an in-kernel device model for the i8254 PIT. This call is only valid |
| 1886 | after enabling in-kernel irqchip support via KVM_CREATE_IRQCHIP. The following |
| 1887 | parameters have to be passed: |
| 1888 | |
| 1889 | struct kvm_pit_config { |
| 1890 | __u32 flags; |
| 1891 | __u32 pad[15]; |
| 1892 | }; |
| 1893 | |
| 1894 | Valid flags are: |
| 1895 | |
| 1896 | #define KVM_PIT_SPEAKER_DUMMY 1 /* emulate speaker port stub */ |
| 1897 | |
Jan Kiszka | b6ddf05 | 2012-04-24 16:40:17 +0200 | [diff] [blame] | 1898 | PIT timer interrupts may use a per-VM kernel thread for injection. If it |
| 1899 | exists, this thread will have a name of the following pattern: |
| 1900 | |
| 1901 | kvm-pit/<owner-process-pid> |
| 1902 | |
| 1903 | When running a guest with elevated priorities, the scheduling parameters of |
| 1904 | this thread may have to be adjusted accordingly. |
| 1905 | |
Jan Kiszka | 0589ff6 | 2012-04-24 16:40:16 +0200 | [diff] [blame] | 1906 | This IOCTL replaces the obsolete KVM_CREATE_PIT. |
| 1907 | |
| 1908 | |
| 1909 | 4.72 KVM_GET_PIT2 |
| 1910 | |
| 1911 | Capability: KVM_CAP_PIT_STATE2 |
| 1912 | Architectures: x86 |
| 1913 | Type: vm ioctl |
| 1914 | Parameters: struct kvm_pit_state2 (out) |
| 1915 | Returns: 0 on success, -1 on error |
| 1916 | |
| 1917 | Retrieves the state of the in-kernel PIT model. Only valid after |
| 1918 | KVM_CREATE_PIT2. The state is returned in the following structure: |
| 1919 | |
| 1920 | struct kvm_pit_state2 { |
| 1921 | struct kvm_pit_channel_state channels[3]; |
| 1922 | __u32 flags; |
| 1923 | __u32 reserved[9]; |
| 1924 | }; |
| 1925 | |
| 1926 | Valid flags are: |
| 1927 | |
| 1928 | /* disable PIT in HPET legacy mode */ |
| 1929 | #define KVM_PIT_FLAGS_HPET_LEGACY 0x00000001 |
| 1930 | |
| 1931 | This IOCTL replaces the obsolete KVM_GET_PIT. |
| 1932 | |
| 1933 | |
| 1934 | 4.73 KVM_SET_PIT2 |
| 1935 | |
| 1936 | Capability: KVM_CAP_PIT_STATE2 |
| 1937 | Architectures: x86 |
| 1938 | Type: vm ioctl |
| 1939 | Parameters: struct kvm_pit_state2 (in) |
| 1940 | Returns: 0 on success, -1 on error |
| 1941 | |
| 1942 | Sets the state of the in-kernel PIT model. Only valid after KVM_CREATE_PIT2. |
| 1943 | See KVM_GET_PIT2 for details on struct kvm_pit_state2. |
| 1944 | |
| 1945 | This IOCTL replaces the obsolete KVM_SET_PIT. |
| 1946 | |
| 1947 | |
Benjamin Herrenschmidt | 5b74716 | 2012-04-26 19:43:42 +0000 | [diff] [blame] | 1948 | 4.74 KVM_PPC_GET_SMMU_INFO |
| 1949 | |
| 1950 | Capability: KVM_CAP_PPC_GET_SMMU_INFO |
| 1951 | Architectures: powerpc |
| 1952 | Type: vm ioctl |
| 1953 | Parameters: None |
| 1954 | Returns: 0 on success, -1 on error |
| 1955 | |
| 1956 | This populates and returns a structure describing the features of |
| 1957 | the "Server" class MMU emulation supported by KVM. |
| 1958 | This can in turn be used by userspace to generate the appropariate |
| 1959 | device-tree properties for the guest operating system. |
| 1960 | |
| 1961 | The structure contains some global informations, followed by an |
| 1962 | array of supported segment page sizes: |
| 1963 | |
| 1964 | struct kvm_ppc_smmu_info { |
| 1965 | __u64 flags; |
| 1966 | __u32 slb_size; |
| 1967 | __u32 pad; |
| 1968 | struct kvm_ppc_one_seg_page_size sps[KVM_PPC_PAGE_SIZES_MAX_SZ]; |
| 1969 | }; |
| 1970 | |
| 1971 | The supported flags are: |
| 1972 | |
| 1973 | - KVM_PPC_PAGE_SIZES_REAL: |
| 1974 | When that flag is set, guest page sizes must "fit" the backing |
| 1975 | store page sizes. When not set, any page size in the list can |
| 1976 | be used regardless of how they are backed by userspace. |
| 1977 | |
| 1978 | - KVM_PPC_1T_SEGMENTS |
| 1979 | The emulated MMU supports 1T segments in addition to the |
| 1980 | standard 256M ones. |
| 1981 | |
| 1982 | The "slb_size" field indicates how many SLB entries are supported |
| 1983 | |
| 1984 | The "sps" array contains 8 entries indicating the supported base |
| 1985 | page sizes for a segment in increasing order. Each entry is defined |
| 1986 | as follow: |
| 1987 | |
| 1988 | struct kvm_ppc_one_seg_page_size { |
| 1989 | __u32 page_shift; /* Base page shift of segment (or 0) */ |
| 1990 | __u32 slb_enc; /* SLB encoding for BookS */ |
| 1991 | struct kvm_ppc_one_page_size enc[KVM_PPC_PAGE_SIZES_MAX_SZ]; |
| 1992 | }; |
| 1993 | |
| 1994 | An entry with a "page_shift" of 0 is unused. Because the array is |
| 1995 | organized in increasing order, a lookup can stop when encoutering |
| 1996 | such an entry. |
| 1997 | |
| 1998 | The "slb_enc" field provides the encoding to use in the SLB for the |
| 1999 | page size. The bits are in positions such as the value can directly |
| 2000 | be OR'ed into the "vsid" argument of the slbmte instruction. |
| 2001 | |
| 2002 | The "enc" array is a list which for each of those segment base page |
| 2003 | size provides the list of supported actual page sizes (which can be |
| 2004 | only larger or equal to the base page size), along with the |
| 2005 | corresponding encoding in the hash PTE. Similarily, the array is |
| 2006 | 8 entries sorted by increasing sizes and an entry with a "0" shift |
| 2007 | is an empty entry and a terminator: |
| 2008 | |
| 2009 | struct kvm_ppc_one_page_size { |
| 2010 | __u32 page_shift; /* Page shift (or 0) */ |
| 2011 | __u32 pte_enc; /* Encoding in the HPTE (>>12) */ |
| 2012 | }; |
| 2013 | |
| 2014 | The "pte_enc" field provides a value that can OR'ed into the hash |
| 2015 | PTE's RPN field (ie, it needs to be shifted left by 12 to OR it |
| 2016 | into the hash PTE second double word). |
| 2017 | |
Alex Williamson | f36992e | 2012-06-29 09:56:16 -0600 | [diff] [blame] | 2018 | 4.75 KVM_IRQFD |
| 2019 | |
| 2020 | Capability: KVM_CAP_IRQFD |
| 2021 | Architectures: x86 |
| 2022 | Type: vm ioctl |
| 2023 | Parameters: struct kvm_irqfd (in) |
| 2024 | Returns: 0 on success, -1 on error |
| 2025 | |
| 2026 | Allows setting an eventfd to directly trigger a guest interrupt. |
| 2027 | kvm_irqfd.fd specifies the file descriptor to use as the eventfd and |
| 2028 | kvm_irqfd.gsi specifies the irqchip pin toggled by this event. When |
| 2029 | an event is tiggered on the eventfd, an interrupt is injected into |
| 2030 | the guest using the specified gsi pin. The irqfd is removed using |
| 2031 | the KVM_IRQFD_FLAG_DEASSIGN flag, specifying both kvm_irqfd.fd |
| 2032 | and kvm_irqfd.gsi. |
| 2033 | |
Alex Williamson | 7a84428 | 2012-09-21 11:58:03 -0600 | [diff] [blame] | 2034 | With KVM_CAP_IRQFD_RESAMPLE, KVM_IRQFD supports a de-assert and notify |
| 2035 | mechanism allowing emulation of level-triggered, irqfd-based |
| 2036 | interrupts. When KVM_IRQFD_FLAG_RESAMPLE is set the user must pass an |
| 2037 | additional eventfd in the kvm_irqfd.resamplefd field. When operating |
| 2038 | in resample mode, posting of an interrupt through kvm_irq.fd asserts |
| 2039 | the specified gsi in the irqchip. When the irqchip is resampled, such |
| 2040 | as from an EOI, the gsi is de-asserted and the user is notifed via |
| 2041 | kvm_irqfd.resamplefd. It is the user's responsibility to re-queue |
| 2042 | the interrupt if the device making use of it still requires service. |
| 2043 | Note that closing the resamplefd is not sufficient to disable the |
| 2044 | irqfd. The KVM_IRQFD_FLAG_RESAMPLE is only necessary on assignment |
| 2045 | and need not be specified with KVM_IRQFD_FLAG_DEASSIGN. |
| 2046 | |
Linus Torvalds | 5fecc9d | 2012-07-24 12:01:20 -0700 | [diff] [blame] | 2047 | 4.76 KVM_PPC_ALLOCATE_HTAB |
Paul Mackerras | 32fad28 | 2012-05-04 02:32:53 +0000 | [diff] [blame] | 2048 | |
| 2049 | Capability: KVM_CAP_PPC_ALLOC_HTAB |
| 2050 | Architectures: powerpc |
| 2051 | Type: vm ioctl |
| 2052 | Parameters: Pointer to u32 containing hash table order (in/out) |
| 2053 | Returns: 0 on success, -1 on error |
| 2054 | |
| 2055 | This requests the host kernel to allocate an MMU hash table for a |
| 2056 | guest using the PAPR paravirtualization interface. This only does |
| 2057 | anything if the kernel is configured to use the Book 3S HV style of |
| 2058 | virtualization. Otherwise the capability doesn't exist and the ioctl |
| 2059 | returns an ENOTTY error. The rest of this description assumes Book 3S |
| 2060 | HV. |
| 2061 | |
| 2062 | There must be no vcpus running when this ioctl is called; if there |
| 2063 | are, it will do nothing and return an EBUSY error. |
| 2064 | |
| 2065 | The parameter is a pointer to a 32-bit unsigned integer variable |
| 2066 | containing the order (log base 2) of the desired size of the hash |
| 2067 | table, which must be between 18 and 46. On successful return from the |
| 2068 | ioctl, it will have been updated with the order of the hash table that |
| 2069 | was allocated. |
| 2070 | |
| 2071 | If no hash table has been allocated when any vcpu is asked to run |
| 2072 | (with the KVM_RUN ioctl), the host kernel will allocate a |
| 2073 | default-sized hash table (16 MB). |
| 2074 | |
| 2075 | If this ioctl is called when a hash table has already been allocated, |
| 2076 | the kernel will clear out the existing hash table (zero all HPTEs) and |
| 2077 | return the hash table order in the parameter. (If the guest is using |
| 2078 | the virtualized real-mode area (VRMA) facility, the kernel will |
| 2079 | re-create the VMRA HPTEs on the next KVM_RUN of any vcpu.) |
| 2080 | |
Cornelia Huck | 416ad65 | 2012-10-02 16:25:37 +0200 | [diff] [blame] | 2081 | 4.77 KVM_S390_INTERRUPT |
| 2082 | |
| 2083 | Capability: basic |
| 2084 | Architectures: s390 |
| 2085 | Type: vm ioctl, vcpu ioctl |
| 2086 | Parameters: struct kvm_s390_interrupt (in) |
| 2087 | Returns: 0 on success, -1 on error |
| 2088 | |
| 2089 | Allows to inject an interrupt to the guest. Interrupts can be floating |
| 2090 | (vm ioctl) or per cpu (vcpu ioctl), depending on the interrupt type. |
| 2091 | |
| 2092 | Interrupt parameters are passed via kvm_s390_interrupt: |
| 2093 | |
| 2094 | struct kvm_s390_interrupt { |
| 2095 | __u32 type; |
| 2096 | __u32 parm; |
| 2097 | __u64 parm64; |
| 2098 | }; |
| 2099 | |
| 2100 | type can be one of the following: |
| 2101 | |
| 2102 | KVM_S390_SIGP_STOP (vcpu) - sigp restart |
| 2103 | KVM_S390_PROGRAM_INT (vcpu) - program check; code in parm |
| 2104 | KVM_S390_SIGP_SET_PREFIX (vcpu) - sigp set prefix; prefix address in parm |
| 2105 | KVM_S390_RESTART (vcpu) - restart |
| 2106 | KVM_S390_INT_VIRTIO (vm) - virtio external interrupt; external interrupt |
| 2107 | parameters in parm and parm64 |
| 2108 | KVM_S390_INT_SERVICE (vm) - sclp external interrupt; sclp parameter in parm |
| 2109 | KVM_S390_INT_EMERGENCY (vcpu) - sigp emergency; source cpu in parm |
| 2110 | KVM_S390_INT_EXTERNAL_CALL (vcpu) - sigp external call; source cpu in parm |
| 2111 | |
| 2112 | Note that the vcpu ioctl is asynchronous to vcpu execution. |
| 2113 | |
Paul Mackerras | a293292 | 2012-11-19 22:57:20 +0000 | [diff] [blame] | 2114 | 4.78 KVM_PPC_GET_HTAB_FD |
| 2115 | |
| 2116 | Capability: KVM_CAP_PPC_HTAB_FD |
| 2117 | Architectures: powerpc |
| 2118 | Type: vm ioctl |
| 2119 | Parameters: Pointer to struct kvm_get_htab_fd (in) |
| 2120 | Returns: file descriptor number (>= 0) on success, -1 on error |
| 2121 | |
| 2122 | This returns a file descriptor that can be used either to read out the |
| 2123 | entries in the guest's hashed page table (HPT), or to write entries to |
| 2124 | initialize the HPT. The returned fd can only be written to if the |
| 2125 | KVM_GET_HTAB_WRITE bit is set in the flags field of the argument, and |
| 2126 | can only be read if that bit is clear. The argument struct looks like |
| 2127 | this: |
| 2128 | |
| 2129 | /* For KVM_PPC_GET_HTAB_FD */ |
| 2130 | struct kvm_get_htab_fd { |
| 2131 | __u64 flags; |
| 2132 | __u64 start_index; |
| 2133 | __u64 reserved[2]; |
| 2134 | }; |
| 2135 | |
| 2136 | /* Values for kvm_get_htab_fd.flags */ |
| 2137 | #define KVM_GET_HTAB_BOLTED_ONLY ((__u64)0x1) |
| 2138 | #define KVM_GET_HTAB_WRITE ((__u64)0x2) |
| 2139 | |
| 2140 | The `start_index' field gives the index in the HPT of the entry at |
| 2141 | which to start reading. It is ignored when writing. |
| 2142 | |
| 2143 | Reads on the fd will initially supply information about all |
| 2144 | "interesting" HPT entries. Interesting entries are those with the |
| 2145 | bolted bit set, if the KVM_GET_HTAB_BOLTED_ONLY bit is set, otherwise |
| 2146 | all entries. When the end of the HPT is reached, the read() will |
| 2147 | return. If read() is called again on the fd, it will start again from |
| 2148 | the beginning of the HPT, but will only return HPT entries that have |
| 2149 | changed since they were last read. |
| 2150 | |
| 2151 | Data read or written is structured as a header (8 bytes) followed by a |
| 2152 | series of valid HPT entries (16 bytes) each. The header indicates how |
| 2153 | many valid HPT entries there are and how many invalid entries follow |
| 2154 | the valid entries. The invalid entries are not represented explicitly |
| 2155 | in the stream. The header format is: |
| 2156 | |
| 2157 | struct kvm_get_htab_header { |
| 2158 | __u32 index; |
| 2159 | __u16 n_valid; |
| 2160 | __u16 n_invalid; |
| 2161 | }; |
| 2162 | |
| 2163 | Writes to the fd create HPT entries starting at the index given in the |
| 2164 | header; first `n_valid' valid entries with contents from the data |
| 2165 | written, then `n_invalid' invalid entries, invalidating any previously |
| 2166 | valid entries found. |
| 2167 | |
Alex Williamson | f36992e | 2012-06-29 09:56:16 -0600 | [diff] [blame] | 2168 | |
Christoffer Dall | 749cf76c | 2013-01-20 18:28:06 -0500 | [diff] [blame] | 2169 | 4.77 KVM_ARM_VCPU_INIT |
| 2170 | |
| 2171 | Capability: basic |
| 2172 | Architectures: arm |
| 2173 | Type: vcpu ioctl |
| 2174 | Parameters: struct struct kvm_vcpu_init (in) |
| 2175 | Returns: 0 on success; -1 on error |
| 2176 | Errors: |
| 2177 | Â EINVAL: Â Â Â the target is unknown, or the combination of features is invalid. |
| 2178 | Â ENOENT: Â Â Â a features bit specified is unknown. |
| 2179 | |
| 2180 | This tells KVM what type of CPU to present to the guest, and what |
| 2181 | optional features it should have. Â This will cause a reset of the cpu |
| 2182 | registers to their initial values. Â If this is not called, KVM_RUN will |
| 2183 | return ENOEXEC for that vcpu. |
| 2184 | |
| 2185 | Note that because some registers reflect machine topology, all vcpus |
| 2186 | should be created before this ioctl is invoked. |
| 2187 | |
Marc Zyngier | aa024c2f | 2013-01-20 18:28:13 -0500 | [diff] [blame] | 2188 | Possible features: |
| 2189 | - KVM_ARM_VCPU_POWER_OFF: Starts the CPU in a power-off state. |
| 2190 | Depends on KVM_CAP_ARM_PSCI. |
| 2191 | |
Christoffer Dall | 749cf76c | 2013-01-20 18:28:06 -0500 | [diff] [blame] | 2192 | |
| 2193 | 4.78 KVM_GET_REG_LIST |
| 2194 | |
| 2195 | Capability: basic |
| 2196 | Architectures: arm |
| 2197 | Type: vcpu ioctl |
| 2198 | Parameters: struct kvm_reg_list (in/out) |
| 2199 | Returns: 0 on success; -1 on error |
| 2200 | Errors: |
| 2201 | Â E2BIG: Â Â Â Â the reg index list is too big to fit in the array specified by |
| 2202 | Â Â Â Â Â Â Â Â Â Â Â Â the user (the number required will be written into n). |
| 2203 | |
| 2204 | struct kvm_reg_list { |
| 2205 | __u64 n; /* number of registers in reg[] */ |
| 2206 | __u64 reg[0]; |
| 2207 | }; |
| 2208 | |
| 2209 | This ioctl returns the guest registers that are supported for the |
| 2210 | KVM_GET_ONE_REG/KVM_SET_ONE_REG calls. |
| 2211 | |
| 2212 | |
Christoffer Dall | 3401d546 | 2013-01-23 13:18:04 -0500 | [diff] [blame] | 2213 | 4.80 KVM_ARM_SET_DEVICE_ADDR |
| 2214 | |
| 2215 | Capability: KVM_CAP_ARM_SET_DEVICE_ADDR |
| 2216 | Architectures: arm |
| 2217 | Type: vm ioctl |
| 2218 | Parameters: struct kvm_arm_device_address (in) |
| 2219 | Returns: 0 on success, -1 on error |
| 2220 | Errors: |
| 2221 | ENODEV: The device id is unknown |
| 2222 | ENXIO: Device not supported on current system |
| 2223 | EEXIST: Address already set |
| 2224 | E2BIG: Address outside guest physical address space |
Christoffer Dall | 330690c | 2013-01-21 19:36:13 -0500 | [diff] [blame^] | 2225 | EBUSY: Address overlaps with other device range |
Christoffer Dall | 3401d546 | 2013-01-23 13:18:04 -0500 | [diff] [blame] | 2226 | |
| 2227 | struct kvm_arm_device_addr { |
| 2228 | __u64 id; |
| 2229 | __u64 addr; |
| 2230 | }; |
| 2231 | |
| 2232 | Specify a device address in the guest's physical address space where guests |
| 2233 | can access emulated or directly exposed devices, which the host kernel needs |
| 2234 | to know about. The id field is an architecture specific identifier for a |
| 2235 | specific device. |
| 2236 | |
| 2237 | ARM divides the id field into two parts, a device id and an address type id |
| 2238 | specific to the individual device. |
| 2239 | |
| 2240 | Â bits: | 63 ... 32 | 31 ... 16 | 15 ... 0 | |
| 2241 | field: | 0x00000000 | device id | addr type id | |
| 2242 | |
| 2243 | ARM currently only require this when using the in-kernel GIC support for the |
| 2244 | hardware VGIC features, using KVM_ARM_DEVICE_VGIC_V2 as the device id. When |
| 2245 | setting the base address for the guest's mapping of the VGIC virtual CPU |
| 2246 | and distributor interface, the ioctl must be called after calling |
| 2247 | KVM_CREATE_IRQCHIP, but before calling KVM_RUN on any of the VCPUs. Calling |
| 2248 | this ioctl twice for any of the base addresses will return -EEXIST. |
| 2249 | |
| 2250 | |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 2251 | 5. The kvm_run structure |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 2252 | ------------------------ |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 2253 | |
| 2254 | Application code obtains a pointer to the kvm_run structure by |
| 2255 | mmap()ing a vcpu fd. From that point, application code can control |
| 2256 | execution by changing fields in kvm_run prior to calling the KVM_RUN |
| 2257 | ioctl, and obtain information about the reason KVM_RUN returned by |
| 2258 | looking up structure members. |
| 2259 | |
| 2260 | struct kvm_run { |
| 2261 | /* in */ |
| 2262 | __u8 request_interrupt_window; |
| 2263 | |
| 2264 | Request that KVM_RUN return when it becomes possible to inject external |
| 2265 | interrupts into the guest. Useful in conjunction with KVM_INTERRUPT. |
| 2266 | |
| 2267 | __u8 padding1[7]; |
| 2268 | |
| 2269 | /* out */ |
| 2270 | __u32 exit_reason; |
| 2271 | |
| 2272 | When KVM_RUN has returned successfully (return value 0), this informs |
| 2273 | application code why KVM_RUN has returned. Allowable values for this |
| 2274 | field are detailed below. |
| 2275 | |
| 2276 | __u8 ready_for_interrupt_injection; |
| 2277 | |
| 2278 | If request_interrupt_window has been specified, this field indicates |
| 2279 | an interrupt can be injected now with KVM_INTERRUPT. |
| 2280 | |
| 2281 | __u8 if_flag; |
| 2282 | |
| 2283 | The value of the current interrupt flag. Only valid if in-kernel |
| 2284 | local APIC is not used. |
| 2285 | |
| 2286 | __u8 padding2[2]; |
| 2287 | |
| 2288 | /* in (pre_kvm_run), out (post_kvm_run) */ |
| 2289 | __u64 cr8; |
| 2290 | |
| 2291 | The value of the cr8 register. Only valid if in-kernel local APIC is |
| 2292 | not used. Both input and output. |
| 2293 | |
| 2294 | __u64 apic_base; |
| 2295 | |
| 2296 | The value of the APIC BASE msr. Only valid if in-kernel local |
| 2297 | APIC is not used. Both input and output. |
| 2298 | |
| 2299 | union { |
| 2300 | /* KVM_EXIT_UNKNOWN */ |
| 2301 | struct { |
| 2302 | __u64 hardware_exit_reason; |
| 2303 | } hw; |
| 2304 | |
| 2305 | If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown |
| 2306 | reasons. Further architecture-specific information is available in |
| 2307 | hardware_exit_reason. |
| 2308 | |
| 2309 | /* KVM_EXIT_FAIL_ENTRY */ |
| 2310 | struct { |
| 2311 | __u64 hardware_entry_failure_reason; |
| 2312 | } fail_entry; |
| 2313 | |
| 2314 | If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due |
| 2315 | to unknown reasons. Further architecture-specific information is |
| 2316 | available in hardware_entry_failure_reason. |
| 2317 | |
| 2318 | /* KVM_EXIT_EXCEPTION */ |
| 2319 | struct { |
| 2320 | __u32 exception; |
| 2321 | __u32 error_code; |
| 2322 | } ex; |
| 2323 | |
| 2324 | Unused. |
| 2325 | |
| 2326 | /* KVM_EXIT_IO */ |
| 2327 | struct { |
| 2328 | #define KVM_EXIT_IO_IN 0 |
| 2329 | #define KVM_EXIT_IO_OUT 1 |
| 2330 | __u8 direction; |
| 2331 | __u8 size; /* bytes */ |
| 2332 | __u16 port; |
| 2333 | __u32 count; |
| 2334 | __u64 data_offset; /* relative to kvm_run start */ |
| 2335 | } io; |
| 2336 | |
Wu Fengguang | 2044892d | 2009-12-24 09:04:16 +0800 | [diff] [blame] | 2337 | If exit_reason is KVM_EXIT_IO, then the vcpu has |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 2338 | executed a port I/O instruction which could not be satisfied by kvm. |
| 2339 | data_offset describes where the data is located (KVM_EXIT_IO_OUT) or |
| 2340 | where kvm expects application code to place the data for the next |
Wu Fengguang | 2044892d | 2009-12-24 09:04:16 +0800 | [diff] [blame] | 2341 | KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a packed array. |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 2342 | |
| 2343 | struct { |
| 2344 | struct kvm_debug_exit_arch arch; |
| 2345 | } debug; |
| 2346 | |
| 2347 | Unused. |
| 2348 | |
| 2349 | /* KVM_EXIT_MMIO */ |
| 2350 | struct { |
| 2351 | __u64 phys_addr; |
| 2352 | __u8 data[8]; |
| 2353 | __u32 len; |
| 2354 | __u8 is_write; |
| 2355 | } mmio; |
| 2356 | |
Wu Fengguang | 2044892d | 2009-12-24 09:04:16 +0800 | [diff] [blame] | 2357 | If exit_reason is KVM_EXIT_MMIO, then the vcpu has |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 2358 | executed a memory-mapped I/O instruction which could not be satisfied |
| 2359 | by kvm. The 'data' member contains the written data if 'is_write' is |
| 2360 | true, and should be filled by application code otherwise. |
| 2361 | |
Alexander Graf | 686de18 | 2012-10-07 15:22:59 +0200 | [diff] [blame] | 2362 | NOTE: For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_DCR |
| 2363 | and KVM_EXIT_PAPR the corresponding |
Alexander Graf | ad0a048 | 2010-03-24 21:48:30 +0100 | [diff] [blame] | 2364 | operations are complete (and guest state is consistent) only after userspace |
| 2365 | has re-entered the kernel with KVM_RUN. The kernel side will first finish |
Marcelo Tosatti | 6796134 | 2010-02-13 16:10:26 -0200 | [diff] [blame] | 2366 | incomplete operations and then check for pending signals. Userspace |
| 2367 | can re-enter the guest with an unmasked signal pending to complete |
| 2368 | pending operations. |
| 2369 | |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 2370 | /* KVM_EXIT_HYPERCALL */ |
| 2371 | struct { |
| 2372 | __u64 nr; |
| 2373 | __u64 args[6]; |
| 2374 | __u64 ret; |
| 2375 | __u32 longmode; |
| 2376 | __u32 pad; |
| 2377 | } hypercall; |
| 2378 | |
Avi Kivity | 647dc49 | 2010-04-01 14:39:21 +0300 | [diff] [blame] | 2379 | Unused. This was once used for 'hypercall to userspace'. To implement |
| 2380 | such functionality, use KVM_EXIT_IO (x86) or KVM_EXIT_MMIO (all except s390). |
| 2381 | Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO. |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 2382 | |
| 2383 | /* KVM_EXIT_TPR_ACCESS */ |
| 2384 | struct { |
| 2385 | __u64 rip; |
| 2386 | __u32 is_write; |
| 2387 | __u32 pad; |
| 2388 | } tpr_access; |
| 2389 | |
| 2390 | To be documented (KVM_TPR_ACCESS_REPORTING). |
| 2391 | |
| 2392 | /* KVM_EXIT_S390_SIEIC */ |
| 2393 | struct { |
| 2394 | __u8 icptcode; |
| 2395 | __u64 mask; /* psw upper half */ |
| 2396 | __u64 addr; /* psw lower half */ |
| 2397 | __u16 ipa; |
| 2398 | __u32 ipb; |
| 2399 | } s390_sieic; |
| 2400 | |
| 2401 | s390 specific. |
| 2402 | |
| 2403 | /* KVM_EXIT_S390_RESET */ |
| 2404 | #define KVM_S390_RESET_POR 1 |
| 2405 | #define KVM_S390_RESET_CLEAR 2 |
| 2406 | #define KVM_S390_RESET_SUBSYSTEM 4 |
| 2407 | #define KVM_S390_RESET_CPU_INIT 8 |
| 2408 | #define KVM_S390_RESET_IPL 16 |
| 2409 | __u64 s390_reset_flags; |
| 2410 | |
| 2411 | s390 specific. |
| 2412 | |
Carsten Otte | e168bf8 | 2012-01-04 10:25:22 +0100 | [diff] [blame] | 2413 | /* KVM_EXIT_S390_UCONTROL */ |
| 2414 | struct { |
| 2415 | __u64 trans_exc_code; |
| 2416 | __u32 pgm_code; |
| 2417 | } s390_ucontrol; |
| 2418 | |
| 2419 | s390 specific. A page fault has occurred for a user controlled virtual |
| 2420 | machine (KVM_VM_S390_UNCONTROL) on it's host page table that cannot be |
| 2421 | resolved by the kernel. |
| 2422 | The program code and the translation exception code that were placed |
| 2423 | in the cpu's lowcore are presented here as defined by the z Architecture |
| 2424 | Principles of Operation Book in the Chapter for Dynamic Address Translation |
| 2425 | (DAT) |
| 2426 | |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 2427 | /* KVM_EXIT_DCR */ |
| 2428 | struct { |
| 2429 | __u32 dcrn; |
| 2430 | __u32 data; |
| 2431 | __u8 is_write; |
| 2432 | } dcr; |
| 2433 | |
| 2434 | powerpc specific. |
| 2435 | |
Alexander Graf | ad0a048 | 2010-03-24 21:48:30 +0100 | [diff] [blame] | 2436 | /* KVM_EXIT_OSI */ |
| 2437 | struct { |
| 2438 | __u64 gprs[32]; |
| 2439 | } osi; |
| 2440 | |
| 2441 | MOL uses a special hypercall interface it calls 'OSI'. To enable it, we catch |
| 2442 | hypercalls and exit with this exit struct that contains all the guest gprs. |
| 2443 | |
| 2444 | If exit_reason is KVM_EXIT_OSI, then the vcpu has triggered such a hypercall. |
| 2445 | Userspace can now handle the hypercall and when it's done modify the gprs as |
| 2446 | necessary. Upon guest entry all guest GPRs will then be replaced by the values |
| 2447 | in this struct. |
| 2448 | |
Paul Mackerras | de56a94 | 2011-06-29 00:21:34 +0000 | [diff] [blame] | 2449 | /* KVM_EXIT_PAPR_HCALL */ |
| 2450 | struct { |
| 2451 | __u64 nr; |
| 2452 | __u64 ret; |
| 2453 | __u64 args[9]; |
| 2454 | } papr_hcall; |
| 2455 | |
| 2456 | This is used on 64-bit PowerPC when emulating a pSeries partition, |
| 2457 | e.g. with the 'pseries' machine type in qemu. It occurs when the |
| 2458 | guest does a hypercall using the 'sc 1' instruction. The 'nr' field |
| 2459 | contains the hypercall number (from the guest R3), and 'args' contains |
| 2460 | the arguments (from the guest R4 - R12). Userspace should put the |
| 2461 | return code in 'ret' and any extra returned values in args[]. |
| 2462 | The possible hypercalls are defined in the Power Architecture Platform |
| 2463 | Requirements (PAPR) document available from www.power.org (free |
| 2464 | developer registration required to access it). |
| 2465 | |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 2466 | /* Fix the size of the union. */ |
| 2467 | char padding[256]; |
| 2468 | }; |
Christian Borntraeger | b9e5dc8 | 2012-01-11 11:20:30 +0100 | [diff] [blame] | 2469 | |
| 2470 | /* |
| 2471 | * shared registers between kvm and userspace. |
| 2472 | * kvm_valid_regs specifies the register classes set by the host |
| 2473 | * kvm_dirty_regs specified the register classes dirtied by userspace |
| 2474 | * struct kvm_sync_regs is architecture specific, as well as the |
| 2475 | * bits for kvm_valid_regs and kvm_dirty_regs |
| 2476 | */ |
| 2477 | __u64 kvm_valid_regs; |
| 2478 | __u64 kvm_dirty_regs; |
| 2479 | union { |
| 2480 | struct kvm_sync_regs regs; |
| 2481 | char padding[1024]; |
| 2482 | } s; |
| 2483 | |
| 2484 | If KVM_CAP_SYNC_REGS is defined, these fields allow userspace to access |
| 2485 | certain guest registers without having to call SET/GET_*REGS. Thus we can |
| 2486 | avoid some system call overhead if userspace has to handle the exit. |
| 2487 | Userspace can query the validity of the structure by checking |
| 2488 | kvm_valid_regs for specific bits. These bits are architecture specific |
| 2489 | and usually define the validity of a groups of registers. (e.g. one bit |
| 2490 | for general purpose registers) |
| 2491 | |
Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 2492 | }; |
Alexander Graf | 821246a | 2011-08-31 10:58:55 +0200 | [diff] [blame] | 2493 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 2494 | |
Alexander Graf | 821246a | 2011-08-31 10:58:55 +0200 | [diff] [blame] | 2495 | 6. Capabilities that can be enabled |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 2496 | ----------------------------------- |
Alexander Graf | 821246a | 2011-08-31 10:58:55 +0200 | [diff] [blame] | 2497 | |
| 2498 | There are certain capabilities that change the behavior of the virtual CPU when |
| 2499 | enabled. To enable them, please see section 4.37. Below you can find a list of |
| 2500 | capabilities and what their effect on the vCPU is when enabling them. |
| 2501 | |
| 2502 | The following information is provided along with the description: |
| 2503 | |
| 2504 | Architectures: which instruction set architectures provide this ioctl. |
| 2505 | x86 includes both i386 and x86_64. |
| 2506 | |
| 2507 | Parameters: what parameters are accepted by the capability. |
| 2508 | |
| 2509 | Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL) |
| 2510 | are not detailed, but errors with specific meanings are. |
| 2511 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 2512 | |
Alexander Graf | 821246a | 2011-08-31 10:58:55 +0200 | [diff] [blame] | 2513 | 6.1 KVM_CAP_PPC_OSI |
| 2514 | |
| 2515 | Architectures: ppc |
| 2516 | Parameters: none |
| 2517 | Returns: 0 on success; -1 on error |
| 2518 | |
| 2519 | This capability enables interception of OSI hypercalls that otherwise would |
| 2520 | be treated as normal system calls to be injected into the guest. OSI hypercalls |
| 2521 | were invented by Mac-on-Linux to have a standardized communication mechanism |
| 2522 | between the guest and the host. |
| 2523 | |
| 2524 | When this capability is enabled, KVM_EXIT_OSI can occur. |
| 2525 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 2526 | |
Alexander Graf | 821246a | 2011-08-31 10:58:55 +0200 | [diff] [blame] | 2527 | 6.2 KVM_CAP_PPC_PAPR |
| 2528 | |
| 2529 | Architectures: ppc |
| 2530 | Parameters: none |
| 2531 | Returns: 0 on success; -1 on error |
| 2532 | |
| 2533 | This capability enables interception of PAPR hypercalls. PAPR hypercalls are |
| 2534 | done using the hypercall instruction "sc 1". |
| 2535 | |
| 2536 | It also sets the guest privilege level to "supervisor" mode. Usually the guest |
| 2537 | runs in "hypervisor" privilege mode with a few missing features. |
| 2538 | |
| 2539 | In addition to the above, it changes the semantics of SDR1. In this mode, the |
| 2540 | HTAB address part of SDR1 contains an HVA instead of a GPA, as PAPR keeps the |
| 2541 | HTAB invisible to the guest. |
| 2542 | |
| 2543 | When this capability is enabled, KVM_EXIT_PAPR_HCALL can occur. |
Scott Wood | dc83b8b | 2011-08-18 15:25:21 -0500 | [diff] [blame] | 2544 | |
Jan Kiszka | 414fa98 | 2012-04-24 16:40:15 +0200 | [diff] [blame] | 2545 | |
Scott Wood | dc83b8b | 2011-08-18 15:25:21 -0500 | [diff] [blame] | 2546 | 6.3 KVM_CAP_SW_TLB |
| 2547 | |
| 2548 | Architectures: ppc |
| 2549 | Parameters: args[0] is the address of a struct kvm_config_tlb |
| 2550 | Returns: 0 on success; -1 on error |
| 2551 | |
| 2552 | struct kvm_config_tlb { |
| 2553 | __u64 params; |
| 2554 | __u64 array; |
| 2555 | __u32 mmu_type; |
| 2556 | __u32 array_len; |
| 2557 | }; |
| 2558 | |
| 2559 | Configures the virtual CPU's TLB array, establishing a shared memory area |
| 2560 | between userspace and KVM. The "params" and "array" fields are userspace |
| 2561 | addresses of mmu-type-specific data structures. The "array_len" field is an |
| 2562 | safety mechanism, and should be set to the size in bytes of the memory that |
| 2563 | userspace has reserved for the array. It must be at least the size dictated |
| 2564 | by "mmu_type" and "params". |
| 2565 | |
| 2566 | While KVM_RUN is active, the shared region is under control of KVM. Its |
| 2567 | contents are undefined, and any modification by userspace results in |
| 2568 | boundedly undefined behavior. |
| 2569 | |
| 2570 | On return from KVM_RUN, the shared region will reflect the current state of |
| 2571 | the guest's TLB. If userspace makes any changes, it must call KVM_DIRTY_TLB |
| 2572 | to tell KVM which entries have been changed, prior to calling KVM_RUN again |
| 2573 | on this vcpu. |
| 2574 | |
| 2575 | For mmu types KVM_MMU_FSL_BOOKE_NOHV and KVM_MMU_FSL_BOOKE_HV: |
| 2576 | - The "params" field is of type "struct kvm_book3e_206_tlb_params". |
| 2577 | - The "array" field points to an array of type "struct |
| 2578 | kvm_book3e_206_tlb_entry". |
| 2579 | - The array consists of all entries in the first TLB, followed by all |
| 2580 | entries in the second TLB. |
| 2581 | - Within a TLB, entries are ordered first by increasing set number. Within a |
| 2582 | set, entries are ordered by way (increasing ESEL). |
| 2583 | - The hash for determining set number in TLB0 is: (MAS2 >> 12) & (num_sets - 1) |
| 2584 | where "num_sets" is the tlb_sizes[] value divided by the tlb_ways[] value. |
| 2585 | - The tsize field of mas1 shall be set to 4K on TLB0, even though the |
| 2586 | hardware ignores this value for TLB0. |