| 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 | 
 | 5 |  | 
 | 6 | The kvm API is a set of ioctls that are issued to control various aspects | 
 | 7 | of a virtual machine.  The ioctls belong to three classes | 
 | 8 |  | 
 | 9 |  - System ioctls: These query and set global attributes which affect the | 
 | 10 |    whole kvm subsystem.  In addition a system ioctl is used to create | 
 | 11 |    virtual machines | 
 | 12 |  | 
 | 13 |  - VM ioctls: These query and set attributes that affect an entire virtual | 
 | 14 |    machine, for example memory layout.  In addition a VM ioctl is used to | 
 | 15 |    create virtual cpus (vcpus). | 
 | 16 |  | 
 | 17 |    Only run VM ioctls from the same process (address space) that was used | 
 | 18 |    to create the VM. | 
 | 19 |  | 
 | 20 |  - vcpu ioctls: These query and set attributes that control the operation | 
 | 21 |    of a single virtual cpu. | 
 | 22 |  | 
 | 23 |    Only run vcpu ioctls from the same thread that was used to create the | 
 | 24 |    vcpu. | 
 | 25 |  | 
| Wu Fengguang | 2044892 | 2009-12-24 09:04:16 +0800 | [diff] [blame] | 26 | 2. File descriptors | 
| Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 27 |  | 
 | 28 | The kvm API is centered around file descriptors.  An initial | 
 | 29 | open("/dev/kvm") obtains a handle to the kvm subsystem; this handle | 
 | 30 | can be used to issue system ioctls.  A KVM_CREATE_VM ioctl on this | 
| Wu Fengguang | 2044892 | 2009-12-24 09:04:16 +0800 | [diff] [blame] | 31 | 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] | 32 | ioctls.  A KVM_CREATE_VCPU ioctl on a VM fd will create a virtual cpu | 
 | 33 | and return a file descriptor pointing to it.  Finally, ioctls on a vcpu | 
 | 34 | fd can be used to control the vcpu, including the important task of | 
 | 35 | actually running guest code. | 
 | 36 |  | 
 | 37 | In general file descriptors can be migrated among processes by means | 
 | 38 | of fork() and the SCM_RIGHTS facility of unix domain socket.  These | 
 | 39 | kinds of tricks are explicitly not supported by kvm.  While they will | 
 | 40 | not cause harm to the host, their actual behavior is not guaranteed by | 
 | 41 | the API.  The only supported use is one virtual machine per process, | 
 | 42 | and one vcpu per thread. | 
 | 43 |  | 
 | 44 | 3. Extensions | 
 | 45 |  | 
 | 46 | As of Linux 2.6.22, the KVM ABI has been stabilized: no backward | 
 | 47 | incompatible change are allowed.  However, there is an extension | 
 | 48 | facility that allows backward-compatible extensions to the API to be | 
 | 49 | queried and used. | 
 | 50 |  | 
 | 51 | The extension mechanism is not based on on the Linux version number. | 
 | 52 | Instead, kvm defines extension identifiers and a facility to query | 
 | 53 | whether a particular extension identifier is available.  If it is, a | 
 | 54 | set of ioctls is available for application use. | 
 | 55 |  | 
 | 56 | 4. API description | 
 | 57 |  | 
 | 58 | This section describes ioctls that can be used to control kvm guests. | 
 | 59 | For each ioctl, the following information is provided along with a | 
 | 60 | description: | 
 | 61 |  | 
 | 62 |   Capability: which KVM extension provides this ioctl.  Can be 'basic', | 
 | 63 |       which means that is will be provided by any kernel that supports | 
 | 64 |       API version 12 (see section 4.1), or a KVM_CAP_xyz constant, which | 
 | 65 |       means availability needs to be checked with KVM_CHECK_EXTENSION | 
 | 66 |       (see section 4.4). | 
 | 67 |  | 
 | 68 |   Architectures: which instruction set architectures provide this ioctl. | 
 | 69 |       x86 includes both i386 and x86_64. | 
 | 70 |  | 
 | 71 |   Type: system, vm, or vcpu. | 
 | 72 |  | 
 | 73 |   Parameters: what parameters are accepted by the ioctl. | 
 | 74 |  | 
 | 75 |   Returns: the return value.  General error numbers (EBADF, ENOMEM, EINVAL) | 
 | 76 |       are not detailed, but errors with specific meanings are. | 
 | 77 |  | 
 | 78 | 4.1 KVM_GET_API_VERSION | 
 | 79 |  | 
 | 80 | Capability: basic | 
 | 81 | Architectures: all | 
 | 82 | Type: system ioctl | 
 | 83 | Parameters: none | 
 | 84 | Returns: the constant KVM_API_VERSION (=12) | 
 | 85 |  | 
 | 86 | This identifies the API version as the stable kvm API. It is not | 
 | 87 | expected that this number will change.  However, Linux 2.6.20 and | 
 | 88 | 2.6.21 report earlier versions; these are not documented and not | 
 | 89 | supported.  Applications should refuse to run if KVM_GET_API_VERSION | 
 | 90 | returns a value other than 12.  If this check passes, all ioctls | 
 | 91 | described as 'basic' will be available. | 
 | 92 |  | 
 | 93 | 4.2 KVM_CREATE_VM | 
 | 94 |  | 
 | 95 | Capability: basic | 
 | 96 | Architectures: all | 
 | 97 | Type: system ioctl | 
 | 98 | Parameters: none | 
 | 99 | Returns: a VM fd that can be used to control the new virtual machine. | 
 | 100 |  | 
 | 101 | The new VM has no virtual cpus and no memory.  An mmap() of a VM fd | 
 | 102 | will access the virtual machine's physical address space; offset zero | 
 | 103 | corresponds to guest physical address zero.  Use of mmap() on a VM fd | 
 | 104 | is discouraged if userspace memory allocation (KVM_CAP_USER_MEMORY) is | 
 | 105 | available. | 
 | 106 |  | 
 | 107 | 4.3 KVM_GET_MSR_INDEX_LIST | 
 | 108 |  | 
 | 109 | Capability: basic | 
 | 110 | Architectures: x86 | 
 | 111 | Type: system | 
 | 112 | Parameters: struct kvm_msr_list (in/out) | 
 | 113 | Returns: 0 on success; -1 on error | 
 | 114 | Errors: | 
 | 115 |   E2BIG:     the msr index list is to be to fit in the array specified by | 
 | 116 |              the user. | 
 | 117 |  | 
 | 118 | struct kvm_msr_list { | 
 | 119 | 	__u32 nmsrs; /* number of msrs in entries */ | 
 | 120 | 	__u32 indices[0]; | 
 | 121 | }; | 
 | 122 |  | 
 | 123 | This ioctl returns the guest msrs that are supported.  The list varies | 
 | 124 | by kvm version and host processor, but does not change otherwise.  The | 
 | 125 | user fills in the size of the indices array in nmsrs, and in return | 
 | 126 | kvm adjusts nmsrs to reflect the actual number of msrs and fills in | 
 | 127 | the indices array with their numbers. | 
 | 128 |  | 
 | 129 | 4.4 KVM_CHECK_EXTENSION | 
 | 130 |  | 
 | 131 | Capability: basic | 
 | 132 | Architectures: all | 
 | 133 | Type: system ioctl | 
 | 134 | Parameters: extension identifier (KVM_CAP_*) | 
 | 135 | Returns: 0 if unsupported; 1 (or some other positive integer) if supported | 
 | 136 |  | 
 | 137 | The API allows the application to query about extensions to the core | 
 | 138 | kvm API.  Userspace passes an extension identifier (an integer) and | 
 | 139 | receives an integer that describes the extension availability. | 
 | 140 | Generally 0 means no and 1 means yes, but some extensions may report | 
 | 141 | additional information in the integer return value. | 
 | 142 |  | 
 | 143 | 4.5 KVM_GET_VCPU_MMAP_SIZE | 
 | 144 |  | 
 | 145 | Capability: basic | 
 | 146 | Architectures: all | 
 | 147 | Type: system ioctl | 
 | 148 | Parameters: none | 
 | 149 | Returns: size of vcpu mmap area, in bytes | 
 | 150 |  | 
 | 151 | The KVM_RUN ioctl (cf.) communicates with userspace via a shared | 
 | 152 | memory region.  This ioctl returns the size of that region.  See the | 
 | 153 | KVM_RUN documentation for details. | 
 | 154 |  | 
 | 155 | 4.6 KVM_SET_MEMORY_REGION | 
 | 156 |  | 
 | 157 | Capability: basic | 
 | 158 | Architectures: all | 
 | 159 | Type: vm ioctl | 
 | 160 | Parameters: struct kvm_memory_region (in) | 
 | 161 | Returns: 0 on success, -1 on error | 
 | 162 |  | 
 | 163 | struct kvm_memory_region { | 
 | 164 | 	__u32 slot; | 
 | 165 | 	__u32 flags; | 
 | 166 | 	__u64 guest_phys_addr; | 
 | 167 | 	__u64 memory_size; /* bytes */ | 
 | 168 | }; | 
 | 169 |  | 
 | 170 | /* for kvm_memory_region::flags */ | 
 | 171 | #define KVM_MEM_LOG_DIRTY_PAGES  1UL | 
 | 172 |  | 
 | 173 | This ioctl allows the user to create or modify a guest physical memory | 
 | 174 | slot.  When changing an existing slot, it may be moved in the guest | 
 | 175 | physical memory space, or its flags may be modified.  It may not be | 
 | 176 | resized.  Slots may not overlap. | 
 | 177 |  | 
 | 178 | The flags field supports just one flag, KVM_MEM_LOG_DIRTY_PAGES, which | 
 | 179 | instructs kvm to keep track of writes to memory within the slot.  See | 
 | 180 | the KVM_GET_DIRTY_LOG ioctl. | 
 | 181 |  | 
 | 182 | It is recommended to use the KVM_SET_USER_MEMORY_REGION ioctl instead | 
 | 183 | of this API, if available.  This newer API allows placing guest memory | 
 | 184 | at specified locations in the host address space, yielding better | 
 | 185 | control and easy access. | 
 | 186 |  | 
 | 187 | 4.6 KVM_CREATE_VCPU | 
 | 188 |  | 
 | 189 | Capability: basic | 
 | 190 | Architectures: all | 
 | 191 | Type: vm ioctl | 
 | 192 | Parameters: vcpu id (apic id on x86) | 
 | 193 | Returns: vcpu fd on success, -1 on error | 
 | 194 |  | 
 | 195 | This API adds a vcpu to a virtual machine.  The vcpu id is a small integer | 
 | 196 | in the range [0, max_vcpus). | 
 | 197 |  | 
 | 198 | 4.7 KVM_GET_DIRTY_LOG (vm ioctl) | 
 | 199 |  | 
 | 200 | Capability: basic | 
 | 201 | Architectures: x86 | 
 | 202 | Type: vm ioctl | 
 | 203 | Parameters: struct kvm_dirty_log (in/out) | 
 | 204 | Returns: 0 on success, -1 on error | 
 | 205 |  | 
 | 206 | /* for KVM_GET_DIRTY_LOG */ | 
 | 207 | struct kvm_dirty_log { | 
 | 208 | 	__u32 slot; | 
 | 209 | 	__u32 padding; | 
 | 210 | 	union { | 
 | 211 | 		void __user *dirty_bitmap; /* one bit per page */ | 
 | 212 | 		__u64 padding; | 
 | 213 | 	}; | 
 | 214 | }; | 
 | 215 |  | 
 | 216 | Given a memory slot, return a bitmap containing any pages dirtied | 
 | 217 | since the last call to this ioctl.  Bit 0 is the first page in the | 
 | 218 | memory slot.  Ensure the entire structure is cleared to avoid padding | 
 | 219 | issues. | 
 | 220 |  | 
 | 221 | 4.8 KVM_SET_MEMORY_ALIAS | 
 | 222 |  | 
 | 223 | Capability: basic | 
 | 224 | Architectures: x86 | 
 | 225 | Type: vm ioctl | 
 | 226 | Parameters: struct kvm_memory_alias (in) | 
 | 227 | Returns: 0 (success), -1 (error) | 
 | 228 |  | 
 | 229 | struct kvm_memory_alias { | 
 | 230 | 	__u32 slot;  /* this has a different namespace than memory slots */ | 
 | 231 | 	__u32 flags; | 
 | 232 | 	__u64 guest_phys_addr; | 
 | 233 | 	__u64 memory_size; | 
 | 234 | 	__u64 target_phys_addr; | 
 | 235 | }; | 
 | 236 |  | 
 | 237 | Defines a guest physical address space region as an alias to another | 
 | 238 | region.  Useful for aliased address, for example the VGA low memory | 
 | 239 | window. Should not be used with userspace memory. | 
 | 240 |  | 
 | 241 | 4.9 KVM_RUN | 
 | 242 |  | 
 | 243 | Capability: basic | 
 | 244 | Architectures: all | 
 | 245 | Type: vcpu ioctl | 
 | 246 | Parameters: none | 
 | 247 | Returns: 0 on success, -1 on error | 
 | 248 | Errors: | 
 | 249 |   EINTR:     an unmasked signal is pending | 
 | 250 |  | 
 | 251 | This ioctl is used to run a guest virtual cpu.  While there are no | 
 | 252 | explicit parameters, there is an implicit parameter block that can be | 
 | 253 | obtained by mmap()ing the vcpu fd at offset 0, with the size given by | 
 | 254 | KVM_GET_VCPU_MMAP_SIZE.  The parameter block is formatted as a 'struct | 
 | 255 | kvm_run' (see below). | 
 | 256 |  | 
 | 257 | 4.10 KVM_GET_REGS | 
 | 258 |  | 
 | 259 | Capability: basic | 
 | 260 | Architectures: all | 
 | 261 | Type: vcpu ioctl | 
 | 262 | Parameters: struct kvm_regs (out) | 
 | 263 | Returns: 0 on success, -1 on error | 
 | 264 |  | 
 | 265 | Reads the general purpose registers from the vcpu. | 
 | 266 |  | 
 | 267 | /* x86 */ | 
 | 268 | struct kvm_regs { | 
 | 269 | 	/* out (KVM_GET_REGS) / in (KVM_SET_REGS) */ | 
 | 270 | 	__u64 rax, rbx, rcx, rdx; | 
 | 271 | 	__u64 rsi, rdi, rsp, rbp; | 
 | 272 | 	__u64 r8,  r9,  r10, r11; | 
 | 273 | 	__u64 r12, r13, r14, r15; | 
 | 274 | 	__u64 rip, rflags; | 
 | 275 | }; | 
 | 276 |  | 
 | 277 | 4.11 KVM_SET_REGS | 
 | 278 |  | 
 | 279 | Capability: basic | 
 | 280 | Architectures: all | 
 | 281 | Type: vcpu ioctl | 
 | 282 | Parameters: struct kvm_regs (in) | 
 | 283 | Returns: 0 on success, -1 on error | 
 | 284 |  | 
 | 285 | Writes the general purpose registers into the vcpu. | 
 | 286 |  | 
 | 287 | See KVM_GET_REGS for the data structure. | 
 | 288 |  | 
 | 289 | 4.12 KVM_GET_SREGS | 
 | 290 |  | 
 | 291 | Capability: basic | 
 | 292 | Architectures: x86 | 
 | 293 | Type: vcpu ioctl | 
 | 294 | Parameters: struct kvm_sregs (out) | 
 | 295 | Returns: 0 on success, -1 on error | 
 | 296 |  | 
 | 297 | Reads special registers from the vcpu. | 
 | 298 |  | 
 | 299 | /* x86 */ | 
 | 300 | struct kvm_sregs { | 
 | 301 | 	struct kvm_segment cs, ds, es, fs, gs, ss; | 
 | 302 | 	struct kvm_segment tr, ldt; | 
 | 303 | 	struct kvm_dtable gdt, idt; | 
 | 304 | 	__u64 cr0, cr2, cr3, cr4, cr8; | 
 | 305 | 	__u64 efer; | 
 | 306 | 	__u64 apic_base; | 
 | 307 | 	__u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64]; | 
 | 308 | }; | 
 | 309 |  | 
 | 310 | interrupt_bitmap is a bitmap of pending external interrupts.  At most | 
 | 311 | one bit may be set.  This interrupt has been acknowledged by the APIC | 
 | 312 | but not yet injected into the cpu core. | 
 | 313 |  | 
 | 314 | 4.13 KVM_SET_SREGS | 
 | 315 |  | 
 | 316 | Capability: basic | 
 | 317 | Architectures: x86 | 
 | 318 | Type: vcpu ioctl | 
 | 319 | Parameters: struct kvm_sregs (in) | 
 | 320 | Returns: 0 on success, -1 on error | 
 | 321 |  | 
 | 322 | Writes special registers into the vcpu.  See KVM_GET_SREGS for the | 
 | 323 | data structures. | 
 | 324 |  | 
 | 325 | 4.14 KVM_TRANSLATE | 
 | 326 |  | 
 | 327 | Capability: basic | 
 | 328 | Architectures: x86 | 
 | 329 | Type: vcpu ioctl | 
 | 330 | Parameters: struct kvm_translation (in/out) | 
 | 331 | Returns: 0 on success, -1 on error | 
 | 332 |  | 
 | 333 | Translates a virtual address according to the vcpu's current address | 
 | 334 | translation mode. | 
 | 335 |  | 
 | 336 | struct kvm_translation { | 
 | 337 | 	/* in */ | 
 | 338 | 	__u64 linear_address; | 
 | 339 |  | 
 | 340 | 	/* out */ | 
 | 341 | 	__u64 physical_address; | 
 | 342 | 	__u8  valid; | 
 | 343 | 	__u8  writeable; | 
 | 344 | 	__u8  usermode; | 
 | 345 | 	__u8  pad[5]; | 
 | 346 | }; | 
 | 347 |  | 
 | 348 | 4.15 KVM_INTERRUPT | 
 | 349 |  | 
 | 350 | Capability: basic | 
 | 351 | Architectures: x86 | 
 | 352 | Type: vcpu ioctl | 
 | 353 | Parameters: struct kvm_interrupt (in) | 
 | 354 | Returns: 0 on success, -1 on error | 
 | 355 |  | 
 | 356 | Queues a hardware interrupt vector to be injected.  This is only | 
 | 357 | useful if in-kernel local APIC is not used. | 
 | 358 |  | 
 | 359 | /* for KVM_INTERRUPT */ | 
 | 360 | struct kvm_interrupt { | 
 | 361 | 	/* in */ | 
 | 362 | 	__u32 irq; | 
 | 363 | }; | 
 | 364 |  | 
 | 365 | Note 'irq' is an interrupt vector, not an interrupt pin or line. | 
 | 366 |  | 
 | 367 | 4.16 KVM_DEBUG_GUEST | 
 | 368 |  | 
 | 369 | Capability: basic | 
 | 370 | Architectures: none | 
 | 371 | Type: vcpu ioctl | 
 | 372 | Parameters: none) | 
 | 373 | Returns: -1 on error | 
 | 374 |  | 
 | 375 | Support for this has been removed.  Use KVM_SET_GUEST_DEBUG instead. | 
 | 376 |  | 
 | 377 | 4.17 KVM_GET_MSRS | 
 | 378 |  | 
 | 379 | Capability: basic | 
 | 380 | Architectures: x86 | 
 | 381 | Type: vcpu ioctl | 
 | 382 | Parameters: struct kvm_msrs (in/out) | 
 | 383 | Returns: 0 on success, -1 on error | 
 | 384 |  | 
 | 385 | Reads model-specific registers from the vcpu.  Supported msr indices can | 
 | 386 | be obtained using KVM_GET_MSR_INDEX_LIST. | 
 | 387 |  | 
 | 388 | struct kvm_msrs { | 
 | 389 | 	__u32 nmsrs; /* number of msrs in entries */ | 
 | 390 | 	__u32 pad; | 
 | 391 |  | 
 | 392 | 	struct kvm_msr_entry entries[0]; | 
 | 393 | }; | 
 | 394 |  | 
 | 395 | struct kvm_msr_entry { | 
 | 396 | 	__u32 index; | 
 | 397 | 	__u32 reserved; | 
 | 398 | 	__u64 data; | 
 | 399 | }; | 
 | 400 |  | 
 | 401 | Application code should set the 'nmsrs' member (which indicates the | 
 | 402 | size of the entries array) and the 'index' member of each array entry. | 
 | 403 | kvm will fill in the 'data' member. | 
 | 404 |  | 
 | 405 | 4.18 KVM_SET_MSRS | 
 | 406 |  | 
 | 407 | Capability: basic | 
 | 408 | Architectures: x86 | 
 | 409 | Type: vcpu ioctl | 
 | 410 | Parameters: struct kvm_msrs (in) | 
 | 411 | Returns: 0 on success, -1 on error | 
 | 412 |  | 
 | 413 | Writes model-specific registers to the vcpu.  See KVM_GET_MSRS for the | 
 | 414 | data structures. | 
 | 415 |  | 
 | 416 | Application code should set the 'nmsrs' member (which indicates the | 
 | 417 | size of the entries array), and the 'index' and 'data' members of each | 
 | 418 | array entry. | 
 | 419 |  | 
 | 420 | 4.19 KVM_SET_CPUID | 
 | 421 |  | 
 | 422 | Capability: basic | 
 | 423 | Architectures: x86 | 
 | 424 | Type: vcpu ioctl | 
 | 425 | Parameters: struct kvm_cpuid (in) | 
 | 426 | Returns: 0 on success, -1 on error | 
 | 427 |  | 
 | 428 | Defines the vcpu responses to the cpuid instruction.  Applications | 
 | 429 | should use the KVM_SET_CPUID2 ioctl if available. | 
 | 430 |  | 
 | 431 |  | 
 | 432 | struct kvm_cpuid_entry { | 
 | 433 | 	__u32 function; | 
 | 434 | 	__u32 eax; | 
 | 435 | 	__u32 ebx; | 
 | 436 | 	__u32 ecx; | 
 | 437 | 	__u32 edx; | 
 | 438 | 	__u32 padding; | 
 | 439 | }; | 
 | 440 |  | 
 | 441 | /* for KVM_SET_CPUID */ | 
 | 442 | struct kvm_cpuid { | 
 | 443 | 	__u32 nent; | 
 | 444 | 	__u32 padding; | 
 | 445 | 	struct kvm_cpuid_entry entries[0]; | 
 | 446 | }; | 
 | 447 |  | 
 | 448 | 4.20 KVM_SET_SIGNAL_MASK | 
 | 449 |  | 
 | 450 | Capability: basic | 
 | 451 | Architectures: x86 | 
 | 452 | Type: vcpu ioctl | 
 | 453 | Parameters: struct kvm_signal_mask (in) | 
 | 454 | Returns: 0 on success, -1 on error | 
 | 455 |  | 
 | 456 | Defines which signals are blocked during execution of KVM_RUN.  This | 
 | 457 | signal mask temporarily overrides the threads signal mask.  Any | 
 | 458 | unblocked signal received (except SIGKILL and SIGSTOP, which retain | 
 | 459 | their traditional behaviour) will cause KVM_RUN to return with -EINTR. | 
 | 460 |  | 
 | 461 | Note the signal will only be delivered if not blocked by the original | 
 | 462 | signal mask. | 
 | 463 |  | 
 | 464 | /* for KVM_SET_SIGNAL_MASK */ | 
 | 465 | struct kvm_signal_mask { | 
 | 466 | 	__u32 len; | 
 | 467 | 	__u8  sigset[0]; | 
 | 468 | }; | 
 | 469 |  | 
 | 470 | 4.21 KVM_GET_FPU | 
 | 471 |  | 
 | 472 | Capability: basic | 
 | 473 | Architectures: x86 | 
 | 474 | Type: vcpu ioctl | 
 | 475 | Parameters: struct kvm_fpu (out) | 
 | 476 | Returns: 0 on success, -1 on error | 
 | 477 |  | 
 | 478 | Reads the floating point state from the vcpu. | 
 | 479 |  | 
 | 480 | /* for KVM_GET_FPU and KVM_SET_FPU */ | 
 | 481 | struct kvm_fpu { | 
 | 482 | 	__u8  fpr[8][16]; | 
 | 483 | 	__u16 fcw; | 
 | 484 | 	__u16 fsw; | 
 | 485 | 	__u8  ftwx;  /* in fxsave format */ | 
 | 486 | 	__u8  pad1; | 
 | 487 | 	__u16 last_opcode; | 
 | 488 | 	__u64 last_ip; | 
 | 489 | 	__u64 last_dp; | 
 | 490 | 	__u8  xmm[16][16]; | 
 | 491 | 	__u32 mxcsr; | 
 | 492 | 	__u32 pad2; | 
 | 493 | }; | 
 | 494 |  | 
 | 495 | 4.22 KVM_SET_FPU | 
 | 496 |  | 
 | 497 | Capability: basic | 
 | 498 | Architectures: x86 | 
 | 499 | Type: vcpu ioctl | 
 | 500 | Parameters: struct kvm_fpu (in) | 
 | 501 | Returns: 0 on success, -1 on error | 
 | 502 |  | 
 | 503 | Writes the floating point state to the vcpu. | 
 | 504 |  | 
 | 505 | /* for KVM_GET_FPU and KVM_SET_FPU */ | 
 | 506 | struct kvm_fpu { | 
 | 507 | 	__u8  fpr[8][16]; | 
 | 508 | 	__u16 fcw; | 
 | 509 | 	__u16 fsw; | 
 | 510 | 	__u8  ftwx;  /* in fxsave format */ | 
 | 511 | 	__u8  pad1; | 
 | 512 | 	__u16 last_opcode; | 
 | 513 | 	__u64 last_ip; | 
 | 514 | 	__u64 last_dp; | 
 | 515 | 	__u8  xmm[16][16]; | 
 | 516 | 	__u32 mxcsr; | 
 | 517 | 	__u32 pad2; | 
 | 518 | }; | 
 | 519 |  | 
| Avi Kivity | 5dadbfd | 2009-08-23 17:08:04 +0300 | [diff] [blame] | 520 | 4.23 KVM_CREATE_IRQCHIP | 
 | 521 |  | 
 | 522 | Capability: KVM_CAP_IRQCHIP | 
 | 523 | Architectures: x86, ia64 | 
 | 524 | Type: vm ioctl | 
 | 525 | Parameters: none | 
 | 526 | Returns: 0 on success, -1 on error | 
 | 527 |  | 
 | 528 | Creates an interrupt controller model in the kernel.  On x86, creates a virtual | 
 | 529 | ioapic, a virtual PIC (two PICs, nested), and sets up future vcpus to have a | 
 | 530 | local APIC.  IRQ routing for GSIs 0-15 is set to both PIC and IOAPIC; GSI 16-23 | 
 | 531 | only go to the IOAPIC.  On ia64, a IOSAPIC is created. | 
 | 532 |  | 
 | 533 | 4.24 KVM_IRQ_LINE | 
 | 534 |  | 
 | 535 | Capability: KVM_CAP_IRQCHIP | 
 | 536 | Architectures: x86, ia64 | 
 | 537 | Type: vm ioctl | 
 | 538 | Parameters: struct kvm_irq_level | 
 | 539 | Returns: 0 on success, -1 on error | 
 | 540 |  | 
 | 541 | Sets the level of a GSI input to the interrupt controller model in the kernel. | 
 | 542 | Requires that an interrupt controller model has been previously created with | 
 | 543 | KVM_CREATE_IRQCHIP.  Note that edge-triggered interrupts require the level | 
 | 544 | to be set to 1 and then back to 0. | 
 | 545 |  | 
 | 546 | struct kvm_irq_level { | 
 | 547 | 	union { | 
 | 548 | 		__u32 irq;     /* GSI */ | 
 | 549 | 		__s32 status;  /* not used for KVM_IRQ_LEVEL */ | 
 | 550 | 	}; | 
 | 551 | 	__u32 level;           /* 0 or 1 */ | 
 | 552 | }; | 
 | 553 |  | 
 | 554 | 4.25 KVM_GET_IRQCHIP | 
 | 555 |  | 
 | 556 | Capability: KVM_CAP_IRQCHIP | 
 | 557 | Architectures: x86, ia64 | 
 | 558 | Type: vm ioctl | 
 | 559 | Parameters: struct kvm_irqchip (in/out) | 
 | 560 | Returns: 0 on success, -1 on error | 
 | 561 |  | 
 | 562 | Reads the state of a kernel interrupt controller created with | 
 | 563 | KVM_CREATE_IRQCHIP into a buffer provided by the caller. | 
 | 564 |  | 
 | 565 | struct kvm_irqchip { | 
 | 566 | 	__u32 chip_id;  /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */ | 
 | 567 | 	__u32 pad; | 
 | 568 |         union { | 
 | 569 | 		char dummy[512];  /* reserving space */ | 
 | 570 | 		struct kvm_pic_state pic; | 
 | 571 | 		struct kvm_ioapic_state ioapic; | 
 | 572 | 	} chip; | 
 | 573 | }; | 
 | 574 |  | 
 | 575 | 4.26 KVM_SET_IRQCHIP | 
 | 576 |  | 
 | 577 | Capability: KVM_CAP_IRQCHIP | 
 | 578 | Architectures: x86, ia64 | 
 | 579 | Type: vm ioctl | 
 | 580 | Parameters: struct kvm_irqchip (in) | 
 | 581 | Returns: 0 on success, -1 on error | 
 | 582 |  | 
 | 583 | Sets the state of a kernel interrupt controller created with | 
 | 584 | KVM_CREATE_IRQCHIP from a buffer provided by the caller. | 
 | 585 |  | 
 | 586 | struct kvm_irqchip { | 
 | 587 | 	__u32 chip_id;  /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */ | 
 | 588 | 	__u32 pad; | 
 | 589 |         union { | 
 | 590 | 		char dummy[512];  /* reserving space */ | 
 | 591 | 		struct kvm_pic_state pic; | 
 | 592 | 		struct kvm_ioapic_state ioapic; | 
 | 593 | 	} chip; | 
 | 594 | }; | 
 | 595 |  | 
| Ed Swierk | ffde22a | 2009-10-15 15:21:43 -0700 | [diff] [blame] | 596 | 4.27 KVM_XEN_HVM_CONFIG | 
 | 597 |  | 
 | 598 | Capability: KVM_CAP_XEN_HVM | 
 | 599 | Architectures: x86 | 
 | 600 | Type: vm ioctl | 
 | 601 | Parameters: struct kvm_xen_hvm_config (in) | 
 | 602 | Returns: 0 on success, -1 on error | 
 | 603 |  | 
 | 604 | Sets the MSR that the Xen HVM guest uses to initialize its hypercall | 
 | 605 | page, and provides the starting address and size of the hypercall | 
 | 606 | blobs in userspace.  When the guest writes the MSR, kvm copies one | 
 | 607 | page of a blob (32- or 64-bit, depending on the vcpu mode) to guest | 
 | 608 | memory. | 
 | 609 |  | 
 | 610 | struct kvm_xen_hvm_config { | 
 | 611 | 	__u32 flags; | 
 | 612 | 	__u32 msr; | 
 | 613 | 	__u64 blob_addr_32; | 
 | 614 | 	__u64 blob_addr_64; | 
 | 615 | 	__u8 blob_size_32; | 
 | 616 | 	__u8 blob_size_64; | 
 | 617 | 	__u8 pad2[30]; | 
 | 618 | }; | 
 | 619 |  | 
| Glauber Costa | afbcf7a | 2009-10-16 15:28:36 -0400 | [diff] [blame] | 620 | 4.27 KVM_GET_CLOCK | 
 | 621 |  | 
 | 622 | Capability: KVM_CAP_ADJUST_CLOCK | 
 | 623 | Architectures: x86 | 
 | 624 | Type: vm ioctl | 
 | 625 | Parameters: struct kvm_clock_data (out) | 
 | 626 | Returns: 0 on success, -1 on error | 
 | 627 |  | 
 | 628 | Gets the current timestamp of kvmclock as seen by the current guest. In | 
 | 629 | conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios | 
 | 630 | such as migration. | 
 | 631 |  | 
 | 632 | struct kvm_clock_data { | 
 | 633 | 	__u64 clock;  /* kvmclock current value */ | 
 | 634 | 	__u32 flags; | 
 | 635 | 	__u32 pad[9]; | 
 | 636 | }; | 
 | 637 |  | 
 | 638 | 4.28 KVM_SET_CLOCK | 
 | 639 |  | 
 | 640 | Capability: KVM_CAP_ADJUST_CLOCK | 
 | 641 | Architectures: x86 | 
 | 642 | Type: vm ioctl | 
 | 643 | Parameters: struct kvm_clock_data (in) | 
 | 644 | Returns: 0 on success, -1 on error | 
 | 645 |  | 
| Wu Fengguang | 2044892 | 2009-12-24 09:04:16 +0800 | [diff] [blame] | 646 | 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] | 647 | In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenarios | 
 | 648 | such as migration. | 
 | 649 |  | 
 | 650 | struct kvm_clock_data { | 
 | 651 | 	__u64 clock;  /* kvmclock current value */ | 
 | 652 | 	__u32 flags; | 
 | 653 | 	__u32 pad[9]; | 
 | 654 | }; | 
 | 655 |  | 
| Jan Kiszka | 3cfc309 | 2009-11-12 01:04:25 +0100 | [diff] [blame] | 656 | 4.29 KVM_GET_VCPU_EVENTS | 
 | 657 |  | 
 | 658 | Capability: KVM_CAP_VCPU_EVENTS | 
 | 659 | Architectures: x86 | 
 | 660 | Type: vm ioctl | 
 | 661 | Parameters: struct kvm_vcpu_event (out) | 
 | 662 | Returns: 0 on success, -1 on error | 
 | 663 |  | 
 | 664 | Gets currently pending exceptions, interrupts, and NMIs as well as related | 
 | 665 | states of the vcpu. | 
 | 666 |  | 
 | 667 | struct kvm_vcpu_events { | 
 | 668 | 	struct { | 
 | 669 | 		__u8 injected; | 
 | 670 | 		__u8 nr; | 
 | 671 | 		__u8 has_error_code; | 
 | 672 | 		__u8 pad; | 
 | 673 | 		__u32 error_code; | 
 | 674 | 	} exception; | 
 | 675 | 	struct { | 
 | 676 | 		__u8 injected; | 
 | 677 | 		__u8 nr; | 
 | 678 | 		__u8 soft; | 
 | 679 | 		__u8 pad; | 
 | 680 | 	} interrupt; | 
 | 681 | 	struct { | 
 | 682 | 		__u8 injected; | 
 | 683 | 		__u8 pending; | 
 | 684 | 		__u8 masked; | 
 | 685 | 		__u8 pad; | 
 | 686 | 	} nmi; | 
 | 687 | 	__u32 sipi_vector; | 
| Jan Kiszka | dab4b91 | 2009-12-06 18:24:15 +0100 | [diff] [blame] | 688 | 	__u32 flags; | 
| Jan Kiszka | 3cfc309 | 2009-11-12 01:04:25 +0100 | [diff] [blame] | 689 | }; | 
 | 690 |  | 
 | 691 | 4.30 KVM_SET_VCPU_EVENTS | 
 | 692 |  | 
 | 693 | Capability: KVM_CAP_VCPU_EVENTS | 
 | 694 | Architectures: x86 | 
 | 695 | Type: vm ioctl | 
 | 696 | Parameters: struct kvm_vcpu_event (in) | 
 | 697 | Returns: 0 on success, -1 on error | 
 | 698 |  | 
 | 699 | Set pending exceptions, interrupts, and NMIs as well as related states of the | 
 | 700 | vcpu. | 
 | 701 |  | 
 | 702 | See KVM_GET_VCPU_EVENTS for the data structure. | 
 | 703 |  | 
| Jan Kiszka | dab4b91 | 2009-12-06 18:24:15 +0100 | [diff] [blame] | 704 | Fields that may be modified asynchronously by running VCPUs can be excluded | 
 | 705 | from the update. These fields are nmi.pending and sipi_vector. Keep the | 
 | 706 | corresponding bits in the flags field cleared to suppress overwriting the | 
 | 707 | current in-kernel state. The bits are: | 
 | 708 |  | 
 | 709 | KVM_VCPUEVENT_VALID_NMI_PENDING - transfer nmi.pending to the kernel | 
 | 710 | KVM_VCPUEVENT_VALID_SIPI_VECTOR - transfer sipi_vector | 
 | 711 |  | 
| Jan Kiszka | 3cfc309 | 2009-11-12 01:04:25 +0100 | [diff] [blame] | 712 |  | 
| Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 713 | 5. The kvm_run structure | 
 | 714 |  | 
 | 715 | Application code obtains a pointer to the kvm_run structure by | 
 | 716 | mmap()ing a vcpu fd.  From that point, application code can control | 
 | 717 | execution by changing fields in kvm_run prior to calling the KVM_RUN | 
 | 718 | ioctl, and obtain information about the reason KVM_RUN returned by | 
 | 719 | looking up structure members. | 
 | 720 |  | 
 | 721 | struct kvm_run { | 
 | 722 | 	/* in */ | 
 | 723 | 	__u8 request_interrupt_window; | 
 | 724 |  | 
 | 725 | Request that KVM_RUN return when it becomes possible to inject external | 
 | 726 | interrupts into the guest.  Useful in conjunction with KVM_INTERRUPT. | 
 | 727 |  | 
 | 728 | 	__u8 padding1[7]; | 
 | 729 |  | 
 | 730 | 	/* out */ | 
 | 731 | 	__u32 exit_reason; | 
 | 732 |  | 
 | 733 | When KVM_RUN has returned successfully (return value 0), this informs | 
 | 734 | application code why KVM_RUN has returned.  Allowable values for this | 
 | 735 | field are detailed below. | 
 | 736 |  | 
 | 737 | 	__u8 ready_for_interrupt_injection; | 
 | 738 |  | 
 | 739 | If request_interrupt_window has been specified, this field indicates | 
 | 740 | an interrupt can be injected now with KVM_INTERRUPT. | 
 | 741 |  | 
 | 742 | 	__u8 if_flag; | 
 | 743 |  | 
 | 744 | The value of the current interrupt flag.  Only valid if in-kernel | 
 | 745 | local APIC is not used. | 
 | 746 |  | 
 | 747 | 	__u8 padding2[2]; | 
 | 748 |  | 
 | 749 | 	/* in (pre_kvm_run), out (post_kvm_run) */ | 
 | 750 | 	__u64 cr8; | 
 | 751 |  | 
 | 752 | The value of the cr8 register.  Only valid if in-kernel local APIC is | 
 | 753 | not used.  Both input and output. | 
 | 754 |  | 
 | 755 | 	__u64 apic_base; | 
 | 756 |  | 
 | 757 | The value of the APIC BASE msr.  Only valid if in-kernel local | 
 | 758 | APIC is not used.  Both input and output. | 
 | 759 |  | 
 | 760 | 	union { | 
 | 761 | 		/* KVM_EXIT_UNKNOWN */ | 
 | 762 | 		struct { | 
 | 763 | 			__u64 hardware_exit_reason; | 
 | 764 | 		} hw; | 
 | 765 |  | 
 | 766 | If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown | 
 | 767 | reasons.  Further architecture-specific information is available in | 
 | 768 | hardware_exit_reason. | 
 | 769 |  | 
 | 770 | 		/* KVM_EXIT_FAIL_ENTRY */ | 
 | 771 | 		struct { | 
 | 772 | 			__u64 hardware_entry_failure_reason; | 
 | 773 | 		} fail_entry; | 
 | 774 |  | 
 | 775 | If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due | 
 | 776 | to unknown reasons.  Further architecture-specific information is | 
 | 777 | available in hardware_entry_failure_reason. | 
 | 778 |  | 
 | 779 | 		/* KVM_EXIT_EXCEPTION */ | 
 | 780 | 		struct { | 
 | 781 | 			__u32 exception; | 
 | 782 | 			__u32 error_code; | 
 | 783 | 		} ex; | 
 | 784 |  | 
 | 785 | Unused. | 
 | 786 |  | 
 | 787 | 		/* KVM_EXIT_IO */ | 
 | 788 | 		struct { | 
 | 789 | #define KVM_EXIT_IO_IN  0 | 
 | 790 | #define KVM_EXIT_IO_OUT 1 | 
 | 791 | 			__u8 direction; | 
 | 792 | 			__u8 size; /* bytes */ | 
 | 793 | 			__u16 port; | 
 | 794 | 			__u32 count; | 
 | 795 | 			__u64 data_offset; /* relative to kvm_run start */ | 
 | 796 | 		} io; | 
 | 797 |  | 
| Wu Fengguang | 2044892 | 2009-12-24 09:04:16 +0800 | [diff] [blame] | 798 | If exit_reason is KVM_EXIT_IO, then the vcpu has | 
| Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 799 | executed a port I/O instruction which could not be satisfied by kvm. | 
 | 800 | data_offset describes where the data is located (KVM_EXIT_IO_OUT) or | 
 | 801 | where kvm expects application code to place the data for the next | 
| Wu Fengguang | 2044892 | 2009-12-24 09:04:16 +0800 | [diff] [blame] | 802 | 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] | 803 |  | 
 | 804 | 		struct { | 
 | 805 | 			struct kvm_debug_exit_arch arch; | 
 | 806 | 		} debug; | 
 | 807 |  | 
 | 808 | Unused. | 
 | 809 |  | 
 | 810 | 		/* KVM_EXIT_MMIO */ | 
 | 811 | 		struct { | 
 | 812 | 			__u64 phys_addr; | 
 | 813 | 			__u8  data[8]; | 
 | 814 | 			__u32 len; | 
 | 815 | 			__u8  is_write; | 
 | 816 | 		} mmio; | 
 | 817 |  | 
| Wu Fengguang | 2044892 | 2009-12-24 09:04:16 +0800 | [diff] [blame] | 818 | If exit_reason is KVM_EXIT_MMIO, then the vcpu has | 
| Avi Kivity | 9c1b96e | 2009-06-09 12:37:58 +0300 | [diff] [blame] | 819 | executed a memory-mapped I/O instruction which could not be satisfied | 
 | 820 | by kvm.  The 'data' member contains the written data if 'is_write' is | 
 | 821 | true, and should be filled by application code otherwise. | 
 | 822 |  | 
 | 823 | 		/* KVM_EXIT_HYPERCALL */ | 
 | 824 | 		struct { | 
 | 825 | 			__u64 nr; | 
 | 826 | 			__u64 args[6]; | 
 | 827 | 			__u64 ret; | 
 | 828 | 			__u32 longmode; | 
 | 829 | 			__u32 pad; | 
 | 830 | 		} hypercall; | 
 | 831 |  | 
 | 832 | Unused. | 
 | 833 |  | 
 | 834 | 		/* KVM_EXIT_TPR_ACCESS */ | 
 | 835 | 		struct { | 
 | 836 | 			__u64 rip; | 
 | 837 | 			__u32 is_write; | 
 | 838 | 			__u32 pad; | 
 | 839 | 		} tpr_access; | 
 | 840 |  | 
 | 841 | To be documented (KVM_TPR_ACCESS_REPORTING). | 
 | 842 |  | 
 | 843 | 		/* KVM_EXIT_S390_SIEIC */ | 
 | 844 | 		struct { | 
 | 845 | 			__u8 icptcode; | 
 | 846 | 			__u64 mask; /* psw upper half */ | 
 | 847 | 			__u64 addr; /* psw lower half */ | 
 | 848 | 			__u16 ipa; | 
 | 849 | 			__u32 ipb; | 
 | 850 | 		} s390_sieic; | 
 | 851 |  | 
 | 852 | s390 specific. | 
 | 853 |  | 
 | 854 | 		/* KVM_EXIT_S390_RESET */ | 
 | 855 | #define KVM_S390_RESET_POR       1 | 
 | 856 | #define KVM_S390_RESET_CLEAR     2 | 
 | 857 | #define KVM_S390_RESET_SUBSYSTEM 4 | 
 | 858 | #define KVM_S390_RESET_CPU_INIT  8 | 
 | 859 | #define KVM_S390_RESET_IPL       16 | 
 | 860 | 		__u64 s390_reset_flags; | 
 | 861 |  | 
 | 862 | s390 specific. | 
 | 863 |  | 
 | 864 | 		/* KVM_EXIT_DCR */ | 
 | 865 | 		struct { | 
 | 866 | 			__u32 dcrn; | 
 | 867 | 			__u32 data; | 
 | 868 | 			__u8  is_write; | 
 | 869 | 		} dcr; | 
 | 870 |  | 
 | 871 | powerpc specific. | 
 | 872 |  | 
 | 873 | 		/* Fix the size of the union. */ | 
 | 874 | 		char padding[256]; | 
 | 875 | 	}; | 
 | 876 | }; |