Lines Matching refs:the
10 - System ioctls: These query and set global attributes which affect the
18 Only run VM ioctls from the same process (address space) that was used
19 to create the VM.
21 - vcpu ioctls: These query and set attributes that control the operation
24 Only run vcpu ioctls from the same thread that was used to create the
32 open("/dev/kvm") obtains a handle to the kvm subsystem; this handle
37 fd can be used to control the vcpu, including the important task of
41 of fork() and the SCM_RIGHTS facility of unix domain socket. These
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,
51 As of Linux 2.6.22, the KVM ABI has been stabilized: no backward
53 facility that allows backward-compatible extensions to the API to be
56 The extension mechanism is not based on the Linux version number.
66 For each ioctl, the following information is provided along with a
75 availability: for kernels that don't support the ioctl,
76 the ioctl returns -ENOTTY.
83 Parameters: what parameters are accepted by the ioctl.
85 Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL)
95 Returns: the constant KVM_API_VERSION (=12)
97 This identifies the API version as the stable kvm API. It is not
111 Returns: a VM fd that can be used to control the new virtual machine.
114 will access the virtual machine's physical address space; offset zero
121 KVM_CAP_S390_UCONTROL and use the flag KVM_VM_S390_UCONTROL as
133 E2BIG: the msr index list is to be to fit in the array specified by
134 the user.
141 This ioctl returns the guest msrs that are supported. The list varies
143 user fills in the size of the indices array in nmsrs, and in return
144 kvm adjusts nmsrs to reflect the actual number of msrs and fills in
145 the indices array with their numbers.
147 Note: if kvm indicates supports MCE (KVM_CAP_MCE), then the MCE bank MSRs are
148 not returned in the MSR list, as different vcpus can have a different number
149 of banks, as set via the KVM_X86_SETUP_MCE ioctl.
160 The API allows the application to query about extensions to the core
162 receives an integer that describes the extension availability.
164 additional information in the integer return value.
167 It is thus encouraged to use the vm ioctl to query for capabilities (available
168 with KVM_CAP_CHECK_EXTENSION_VM on the vm fd)
179 memory region. This ioctl returns the size of that region. See the
203 in the range [0, max_vcpus).
205 The recommended max_vcpus value can be retrieved using the KVM_CAP_NR_VCPUS of
206 the KVM_CHECK_EXTENSION ioctl() at run-time.
207 The maximum possible value for max_vcpus can be retrieved using the
208 KVM_CAP_MAX_VCPUS of the KVM_CHECK_EXTENSION ioctl() at run-time.
210 If the KVM_CAP_NR_VCPUS does not exist, you should assume that max_vcpus is 4
212 If the KVM_CAP_MAX_VCPUS does not exist, you should assume that max_vcpus is
213 same as the value returned from KVM_CAP_NR_VCPUS.
215 On powerpc using book3s_hv mode, the vcpus are mapped onto virtual
216 threads in one or more virtual CPU cores. (This is because the
217 hardware requires all the hardware threads in a CPU core to be in the
218 same partition.) The KVM_CAP_PPC_SMT capability indicates the number
220 dividing the vcpu id by the number of vcpus per vcore. The vcpus in a
221 given vcore will always be in the same physical core as each other
223 Userspace can control the threading (SMT) mode of the guest by its
226 of the number of vcpus per vcore.
229 machines, the resulting vcpu fd can be memory mapped at page offset
230 KVM_S390_SIE_PAGE_OFFSET in order to obtain a memory map of the virtual
253 since the last call to this ioctl. Bit 0 is the first page in the
254 memory slot. Ensure the entire structure is cleared to avoid padding
258 the address space for which you want to return the dirty bitmap.
259 They must be less than the value that KVM_CHECK_EXTENSION returns for
260 the KVM_CAP_MULTI_ADDRESS_SPACE capability.
286 obtained by mmap()ing the vcpu fd at offset 0, with the size given by
299 Reads the general purpose registers from the vcpu.
329 Writes the general purpose registers into the vcpu.
331 See KVM_GET_REGS for the data structure.
342 Reads special registers from the vcpu.
358 one bit may be set. This interrupt has been acknowledged by the APIC
359 but not yet injected into the cpu core.
370 Writes special registers into the vcpu. See KVM_GET_SREGS for the
382 Translates a virtual address according to the vcpu's current address
418 -EINVAL the the irq number is invalid
419 -ENXIO if the PIC is in the kernel
420 -EFAULT if the pointer is invalid
423 ioctl is useful if the in-kernel PIC is not used.
432 This injects an edge type external interrupt into the guest once it's ready
433 to receive interrupts. When injected, the interrupt is done.
443 This injects a level type external interrupt into the guest context. The
449 Note that any value for 'irq' other than the ones stated above is invalid
454 Queues an external interrupt to be injected into the virtual CPU. A negative
455 interrupt number dequeues the interrupt.
477 Reads model-specific registers from the vcpu. Supported msr indices can
493 Application code should set the 'nmsrs' member (which indicates the
494 size of the entries array) and the 'index' member of each array entry.
495 kvm will fill in the 'data' member.
506 Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the
509 Application code should set the 'nmsrs' member (which indicates the
510 size of the entries array), and the 'index' and 'data' members of each
522 Defines the vcpu responses to the cpuid instruction. Applications
523 should use the KVM_SET_CPUID2 ioctl if available.
552 signal mask temporarily overrides the threads signal mask. Any
556 Note the signal will only be delivered if not blocked by the original
574 Reads the floating point state from the vcpu.
600 Writes the floating point state to the vcpu.
626 Creates an interrupt controller model in the kernel.
629 PIC and IOAPIC; GSI 16-23 only go to the IOAPIC.
630 On ARM/arm64, a GICv2 is created. Any other GIC versions require the usage of
635 Note that on s390 the KVM_CAP_S390_IRQCHIP vm capability needs to be enabled
647 Sets the level of a GSI input to the interrupt controller model in the kernel.
650 interrupts require the level to be set to 1 and then back to 0.
653 does not matter for the level field of struct kvm_irq_level: 1 always
656 x86 allows the operating system to program the interrupt polarity
658 to consider the polarity. However, due to bitrot in the handling of
659 active-low interrupts, the above convention is now valid on x86 too.
661 should not present interrupts to the guest as active-low unless this
662 capability is present (or unless it is not using the in-kernel irqchip,
666 ARM/arm64 can signal an interrupt either at the CPU level, or at the
667 in-kernel irqchip (GIC), and for in-kernel irqchip can tell the GIC to
674 The irq_type field has the following values:
677 (the vcpu_index field is ignored)
680 (The irq_id field thus corresponds nicely to the IRQ ID in the ARM GIC specs)
682 In both cases, level is used to assert/deassert the line.
701 Reads the state of a kernel interrupt controller created with
702 KVM_CREATE_IRQCHIP into a buffer provided by the caller.
723 Sets the state of a kernel interrupt controller created with
724 KVM_CREATE_IRQCHIP from a buffer provided by the caller.
745 Sets the MSR that the Xen HVM guest uses to initialize its hypercall
746 page, and provides the starting address and size of the hypercall
747 blobs in userspace. When the guest writes the MSR, kvm copies one
748 page of a blob (32- or 64-bit, depending on the vcpu mode) to guest
770 Gets the current timestamp of kvmclock as seen by the current guest. In
789 Sets the current timestamp of kvmclock to the value specified in its parameter.
810 states of the vcpu.
842 Only two fields are defined in the flags field:
844 - KVM_VCPUEVENT_VALID_SHADOW may be set in the flags field to signal that
847 - KVM_VCPUEVENT_VALID_SMM may be set in the flags field to signal that
859 Set pending exceptions, interrupts, and NMIs as well as related states of the
862 See KVM_GET_VCPU_EVENTS for the data structure.
865 from the update. These fields are nmi.pending, sipi_vector, smi.smm,
866 smi.pending. Keep the corresponding bits in the flags field cleared to
867 suppress overwriting the current in-kernel state. The bits are:
869 KVM_VCPUEVENT_VALID_NMI_PENDING - transfer nmi.pending to the kernel
871 KVM_VCPUEVENT_VALID_SMM - transfer the smi sub-struct.
874 the flags field to signal that interrupt.shadow contains a valid state and
875 shall be written into the VCPU.
888 Reads debug registers from the vcpu.
907 Writes debug registers into the vcpu.
909 See KVM_GET_DEBUGREGS for the data structure. The flags field is unused
926 __u64 userspace_addr; /* start of the userspace allocated memory */
933 This ioctl allows the user to create or modify a guest physical memory
934 slot. When changing an existing slot, it may be moved in the guest
939 specifies the address space which is being modified. They must be
940 less than the value that KVM_CHECK_EXTENSION returns for the
942 are unrelated; the restriction on overlapping slots only applies within
945 Memory for the region is taken starting at the address denoted by the
947 the entire memory slot size. Any object may back this memory, including
950 It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr
951 be identical. This allows large pages in the guest to be backed by large
952 pages in the host.
956 writes to memory within the slot. See KVM_GET_DIRTY_LOG ioctl to know how to
961 When the KVM_CAP_SYNC_MMU capability is available, changes in the backing of
962 the memory region are automatically reflected into the guest. For example, an
963 mmap() that affects the region will be made visible immediately. Another
966 It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl.
979 This ioctl defines the physical address of a three-page region in the guest
980 physical address space. The region must be within the first 4GB of the
986 because of a quirk in the virtualization implementation (see the internals
999 +Not all extensions are enabled by default. Using this ioctl the application
1000 can enable an extension, making it available to the guest.
1005 To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should
1021 function properly, this is the place to put them.
1026 The vcpu ioctl should be used for vcpu-specific capabilities, the vm ioctl
1041 Returns the vcpu's current "multiprocessing state" (though also valid on
1046 - KVM_MP_STATE_RUNNABLE: the vcpu is currently running [x86,arm/arm64]
1047 - KVM_MP_STATE_UNINITIALIZED: the vcpu is an application processor (AP)
1049 - KVM_MP_STATE_INIT_RECEIVED: the vcpu has received an INIT signal, and is
1051 - KVM_MP_STATE_HALTED: the vcpu has executed a HLT instruction and
1053 - KVM_MP_STATE_SIPI_RECEIVED: the vcpu has just received a SIPI (vector
1055 - KVM_MP_STATE_STOPPED: the vcpu is stopped [s390,arm/arm64]
1056 - KVM_MP_STATE_CHECK_STOP: the vcpu is in a special error state [s390]
1057 - KVM_MP_STATE_OPERATING: the vcpu is operating (running or halted)
1059 - KVM_MP_STATE_LOAD: the vcpu is in a special load/startup state
1063 in-kernel irqchip, the multiprocessing state must be maintained by userspace on
1069 KVM_MP_STATE_RUNNABLE which reflect if the vcpu is paused or not.
1079 Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for
1083 in-kernel irqchip, the multiprocessing state must be maintained by userspace on
1089 KVM_MP_STATE_RUNNABLE which reflect if the vcpu should be paused or not.
1099 This ioctl defines the physical address of a one-page region in the guest
1100 physical address space. The region must be within the first 4GB of the
1106 because of a quirk in the virtualization implementation (see the internals
1118 Define which vcpu is the Bootstrap Processor (BSP). Values are the same
1119 as the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the default
1135 This ioctl would copy current vcpu's xsave struct to the userspace.
1150 This ioctl would copy userspace's xsave struct to the kernel.
1174 This ioctl would copy current vcpu's xcrs to the userspace.
1198 This ioctl would set vcpu's xcr to the value userspace specified.
1230 This ioctl returns x86 cpuid features which are supported by both the hardware
1231 and kvm. Userspace can use the information returned by this ioctl to
1234 example, the user may wish to constrain cpuid to emulate older hardware,
1238 with the 'nent' field indicating the number of entries in the variable-size
1239 array 'entries'. If the number of entries is too low to describe the cpu
1240 capabilities, an error (E2BIG) is returned. If the number is too high,
1241 the 'nent' field is adjusted and an error (ENOMEM) is returned. If the
1242 number is just right, the 'nent' field is adjusted to the number of valid
1243 entries in the 'entries' array, which is then filled.
1245 The entries returned are the host cpuid as returned by the cpuid instruction,
1247 x2apic), may not be present in the host cpu, but are exposed by kvm if it can
1250 function: the eax value used to obtain the entry
1251 index: the ecx value used to obtain the entry (for entries that are
1253 flags: an OR of zero or more of the following:
1255 if the index field is valid
1258 invocations; there will be several entries with the same function,
1262 the first entry to be read by a cpu
1263 eax, ebx, ecx, edx: the values returned by the cpuid instruction for
1267 as false, since the feature depends on KVM_CREATE_IRQCHIP for local APIC
1272 if that returns true and you use KVM_CREATE_IRQCHIP, or if you emulate the
1273 feature in userspace, then you can enable the feature for KVM_SET_CPUID2.
1290 This ioctl fetches PV specific information that need to be passed to the guest
1291 using the device tree or other means from vm context.
1296 additional piece of information will be set in the flags bitmap.
1300 /* the host supports the ePAPR idle hcall
1311 Assigns a host PCI device to the VM.
1324 The PCI device is specified by the triple segnr, busnr, and devfn.
1334 If KVM_DEV_ASSIGN_PCI_2_3 is set, the kernel will manage legacy INTx interrupts
1335 via the PCI-2.3-compliant device-level mask, thus enable IRQ sharing with other
1336 assigned devices or host devices. KVM_DEV_ASSIGN_MASK_INTX specifies the
1337 guest's view on the INTx mask, see KVM_ASSIGN_SET_INTX_MASK for details.
1340 isolation of the device. Usages not specifying this flag are deprecated.
1344 access to the PCI sysfs resource files associated with the device.
1363 See KVM_ASSIGN_PCI_DEVICE for the data structure. Only assigned_dev_id is
1364 used in kvm_assigned_pci_dev to identify the device.
1402 It is not valid to specify multiple types per host or guest IRQ. However, the
1422 See KVM_ASSIGN_DEV_IRQ for the data structure. The target device is specified
1423 by assigned_dev_id, flags must correspond to the IRQ type specified on
1435 Sets the GSI routing table entries, overwriting any previously set entries.
1443 No flags are specified so far, the corresponding field must be set to zero.
1463 No flags are specified so far, the corresponding field must be set to zero.
1494 Set the number of MSI-X interrupts for an assigned device. The number is
1495 reset again by terminating the MSI-X assignment of the device via
1516 Specifies the routing of an MSI-X assigned device interrupt to a GSI. Setting
1517 the GSI vector to zero means disabling the interrupt.
1522 __u16 entry; /* The index of entry in the MSI-X table */
1541 Specifies the tsc frequency for the virtual machine. The unit of the
1553 Returns the tsc frequency of the guest. The unit of the return value is
1554 KHz. If the host has unstable tsc this ioctl returns -EIO instead as an
1571 Reads the Local APIC registers and copies them into the input argument. The
1572 data format and layout are the same as documented in the architecture manual.
1588 Copies the input argument into the Local APIC registers. The data format
1589 and layout are the same as documented in the architecture manual.
1601 within the guest. A guest write in the registered address will signal the
1613 For the special case of virtio-ccw devices on s390, the ioevent is matched
1624 If datamatch flag is set, the event will be signaled only if the written value
1625 to the registered address is equal to datamatch in struct kvm_ioeventfd.
1627 For virtio-ccw devices, addr contains the subchannel id and datamatch the
1631 the kernel will ignore the length of guest write and may get a faster vmexit.
1632 The speedup may only apply to specific architectures, but the ioeventfd will
1648 This must be called whenever userspace has changed an entry in the shared
1649 TLB, prior to calling KVM_RUN on the associated vcpu.
1651 The "bitmap" field is the userspace address of an array. This array
1652 consists of a number of bits, equal to the total number of TLB entries as
1653 determined by the last successful call to KVM_CONFIG_TLB, rounded up to the
1656 Each bit corresponds to one TLB entry, ordered the same as in the shared TLB
1659 The array is little-endian: the bit 0 is the least significant bit of the
1660 first byte, bit 8 is the least significant bit of the second byte, etc.
1664 should skip processing the bitmap and just invalidate everything. It must
1665 be set to the number of set bits in the bitmap.
1676 Allows userspace to mask PCI INTx interrupts from the assigned device. The
1677 kernel will not deliver INTx interrupts to the guest between setting and
1682 older devices lacking this support. Userspace is responsible for emulating the
1683 read value of the INTx disable bit in the guest visible PCI command register.
1684 When modifying the INTx disable state, userspace should precede updating the
1685 physical device command register by calling this ioctl to inform the kernel of
1686 the new intended INTx mask state.
1688 Note that the kernel uses the device INTx disable bit to internally manage the
1690 therefore not match the expected value. Writes should always use the guest
1691 intended INTx disable value rather than attempting to read-copy-update the
1692 current physical device state. Races between user and kernel updates to the
1693 INTx disable bit are handled lazily in the kernel. It's possible the device
1694 may generate unintended interrupts, but they will not be injected into the
1697 See KVM_ASSIGN_DEV_IRQ for the data structure. The target device is specified
1698 by assigned_dev_id. In the flags field, only KVM_DEV_ASSIGN_MASK_INTX is
1708 Returns: file descriptor for manipulating the created TCE table
1721 The liobn field gives the logical IO bus number for which to create a
1722 TCE table. The window_size field specifies the size of the DMA window
1723 which this TCE table will translate - the table will contain one 64
1724 bit TCE entry for every 4kiB of the DMA window.
1726 When the guest issues an H_PUT_TCE hcall on a liobn for which a TCE
1727 table has been created using this ioctl(), the kernel will handle it
1728 in real mode, updating the TCE table. H_PUT_TCE calls for other
1732 to map the created TCE table into userspace. This lets userspace read
1733 the entries written by kernel-handled H_PUT_TCE calls, and also lets
1734 userspace update the TCE table directly which is useful in some
1744 Returns: file descriptor for mapping the allocated RMA
1746 This allocates a Real Mode Area (RMA) from the pool allocated at boot
1747 time by the kernel. An RMA is a physically-contiguous, aligned region
1748 of memory used on older POWER processors to provide the memory which
1750 POWER processors support a set of sizes for the RMA that usually
1759 to map the allocated RMA into userspace. The mapped area can then be
1760 passed to the KVM_SET_USER_MEMORY_REGION ioctl to establish it as the
1761 RMA for a virtual machine. The size of the RMA in bytes (which is
1762 fixed at host kernel boot time) is returned in the rma_size field of
1763 the argument structure.
1765 The KVM_CAP_PPC_RMA capability is 1 or 2 if the KVM_ALLOCATE_RMA ioctl
1766 is supported; 2 if the processor requires all virtual machines to have
1767 an RMA, or 1 if the processor can use an RMA but doesn't require it,
1768 because it supports the Virtual RMA (VRMA) facility.
1779 Queues an NMI on the thread's vcpu. Note this is well defined only
1781 between the virtual cpu core and virtual local APIC. After KVM_CREATE_IRQCHIP
1782 has been called, this interface is completely emulated within the kernel.
1784 To use this to emulate the LINT1 input with KVM_CREATE_IRQCHIP, use the
1787 - pause the vcpu
1788 - read the local APIC's state (KVM_GET_LAPIC)
1789 - check whether changing LINT1 will queue an NMI (see the LVT entry for LINT1)
1791 - resume the vcpu
1793 Some guests configure the LINT1 NMI input to cause a panic, aiding in
1812 This ioctl maps the memory at "user_addr" with the length "length" to
1813 the vcpu's address space starting at "vcpu_addr". All parameters need to
1832 This ioctl unmaps the memory in the vcpu's address space starting at
1833 "vcpu_addr" with the length "length". The field "user_addr" is ignored.
1845 This call creates a page table entry on the virtual cpu's address space
1846 (for user controlled virtual machines) or the virtual machine's address
1848 thus it's recommended to access subject memory page via the user page
1850 controlled virtual machines to fault in the virtual cpu's lowcore pages
1851 prior to calling the KVM_RUN ioctl.
1868 defined by user space with the passed in struct kvm_one_reg, where id
1869 refers to the register identifier as described below and addr is a pointer
1870 to a variable with the respective size. There can be architecture agnostic
1872 and their own constants and width. To keep track of the implemented
2034 ARM registers are mapped using the lower 32 bits. The upper 16 of that
2035 is the register group type, or coprocessor number:
2037 ARM core registers have the following id bit patterns:
2038 0x4020 0000 0010 <index into the kvm_regs struct:16>
2040 ARM 32-bit CP15 registers have the following id bit patterns:
2043 ARM 64-bit CP15 registers have the following id bit patterns:
2049 ARM 32-bit VFP control registers have the following id bit patterns:
2052 ARM 64-bit FP registers have the following id bit patterns:
2056 arm64 registers are mapped using the lower 32 bits. The upper 16 of
2057 that is the register group type, or coprocessor number:
2059 arm64 core/FP-SIMD registers have the following id bit patterns. Note
2060 that the size of the access is variable, as the kvm_regs structure
2062 value in the kvm_regs structure seen as a 32bit array.
2063 0x60x0 0000 0010 <index into the kvm_regs struct:16>
2068 arm64 system registers have the following id bit patterns:
2072 MIPS registers are mapped using the lower 32 bits. The upper 16 of that is
2073 the register group type:
2075 MIPS core registers (see above) have the following id bit patterns:
2078 MIPS CP0 registers (see KVM_REG_MIPS_CP0_* above) have the following id bit
2083 MIPS KVM control registers (see above) have the following id bit patterns:
2086 MIPS FPU registers (see KVM_REG_MIPS_FPR_{32,64}() above) have the following
2087 id bit patterns depending on the size of the register being accessed. They are
2088 always accessed according to the current guest FPU mode (Status.FR and
2089 Config5.FRE), i.e. as the guest would see them, and they become unpredictable
2090 if the guest FPU mode is changed. MIPS SIMD Architecture (MSA) vector
2092 overlap the FPU registers:
2097 MIPS FPU control registers (see KVM_REG_MIPS_FCR_{IR,CSR} above) have the
2101 MIPS MSA control registers (see KVM_REG_MIPS_MSA_{IR,CSR} above) have the
2114 This ioctl allows to receive the value of a single register implemented
2115 in a vcpu. The register to read is indicated by the "id" field of the
2116 kvm_one_reg struct passed in. On success, the register value can be found
2117 at the memory location pointed to by "addr".
2119 The list of registers accessible using this interface is identical to the
2131 This signals to the host kernel that the specified guest is being paused by
2132 userspace. The host will set a flag in the pvclock structure that is checked
2133 from the soft lockup watchdog. The flag is part of the pvclock structure that
2134 is shared between guest and host, specifically the second bit of the flags
2135 field of the pvclock_vcpu_time_info structure. It will be set exclusively by
2136 the host and read/cleared exclusively by the guest. The guest operation of
2137 checking and clearing the flag must an atomic operation so
2139 where the guest will clear the flag: when the soft lockup watchdog timer resets
2141 after pausing the vcpu, but before it is resumed.
2150 Returns: >0 on delivery, 0 if guest blocked the MSI, and -1 on error
2174 Creates an in-kernel device model for the i8254 PIT. This call is only valid
2188 exists, this thread will have a name of the following pattern:
2192 When running a guest with elevated priorities, the scheduling parameters of
2195 This IOCTL replaces the obsolete KVM_CREATE_PIT.
2206 Retrieves the state of the in-kernel PIT model. Only valid after
2207 KVM_CREATE_PIT2. The state is returned in the following structure:
2220 This IOCTL replaces the obsolete KVM_GET_PIT.
2231 Sets the state of the in-kernel PIT model. Only valid after KVM_CREATE_PIT2.
2234 This IOCTL replaces the obsolete KVM_SET_PIT.
2245 This populates and returns a structure describing the features of
2246 the "Server" class MMU emulation supported by KVM.
2247 This can in turn be used by userspace to generate the appropriate
2248 device-tree properties for the guest operating system.
2263 When that flag is set, guest page sizes must "fit" the backing
2264 store page sizes. When not set, any page size in the list can
2268 The emulated MMU supports 1T segments in addition to the
2273 The "sps" array contains 8 entries indicating the supported base
2283 An entry with a "page_shift" of 0 is unused. Because the array is
2287 The "slb_enc" field provides the encoding to use in the SLB for the
2288 page size. The bits are in positions such as the value can directly
2289 be OR'ed into the "vsid" argument of the slbmte instruction.
2292 size provides the list of supported actual page sizes (which can be
2293 only larger or equal to the base page size), along with the
2294 corresponding encoding in the hash PTE. Similarly, the array is
2300 __u32 pte_enc; /* Encoding in the HPTE (>>12) */
2303 The "pte_enc" field provides a value that can OR'ed into the hash
2305 into the hash PTE second double word).
2316 kvm_irqfd.fd specifies the file descriptor to use as the eventfd and
2317 kvm_irqfd.gsi specifies the irqchip pin toggled by this event. When
2318 an event is triggered on the eventfd, an interrupt is injected into
2319 the guest using the specified gsi pin. The irqfd is removed using
2320 the KVM_IRQFD_FLAG_DEASSIGN flag, specifying both kvm_irqfd.fd
2325 interrupts. When KVM_IRQFD_FLAG_RESAMPLE is set the user must pass an
2326 additional eventfd in the kvm_irqfd.resamplefd field. When operating
2328 the specified gsi in the irqchip. When the irqchip is resampled, such
2329 as from an EOI, the gsi is de-asserted and the user is notified via
2330 kvm_irqfd.resamplefd. It is the user's responsibility to re-queue
2331 the interrupt if the device making use of it still requires service.
2332 Note that closing the resamplefd is not sufficient to disable the
2336 On ARM/ARM64, the gsi field in the kvm_irqfd struct specifies the Shared
2337 Peripheral Interrupt (SPI) index, such that the GIC interrupt ID is
2348 This requests the host kernel to allocate an MMU hash table for a
2349 guest using the PAPR paravirtualization interface. This only does
2350 anything if the kernel is configured to use the Book 3S HV style of
2351 virtualization. Otherwise the capability doesn't exist and the ioctl
2359 containing the order (log base 2) of the desired size of the hash
2360 table, which must be between 18 and 46. On successful return from the
2361 ioctl, it will have been updated with the order of the hash table that
2365 (with the KVM_RUN ioctl), the host kernel will allocate a
2369 the kernel will clear out the existing hash table (zero all HPTEs) and
2370 return the hash table order in the parameter. (If the guest is using
2371 the virtualized real-mode area (VRMA) facility, the kernel will
2372 re-create the VMRA HPTEs on the next KVM_RUN of any vcpu.)
2382 Allows to inject an interrupt to the guest. Interrupts can be floating
2383 (vm ioctl) or per cpu (vcpu ioctl), depending on the interrupt type.
2393 type can be one of the following:
2415 Note that the vcpu ioctl is asynchronous to vcpu execution.
2425 This returns a file descriptor that can be used either to read out the
2426 entries in the guest's hashed page table (HPT), or to write entries to
2427 initialize the HPT. The returned fd can only be written to if the
2428 KVM_GET_HTAB_WRITE bit is set in the flags field of the argument, and
2443 The `start_index' field gives the index in the HPT of the entry at
2446 Reads on the fd will initially supply information about all
2447 "interesting" HPT entries. Interesting entries are those with the
2448 bolted bit set, if the KVM_GET_HTAB_BOLTED_ONLY bit is set, otherwise
2449 all entries. When the end of the HPT is reached, the read() will
2450 return. If read() is called again on the fd, it will start again from
2451 the beginning of the HPT, but will only return HPT entries that have
2457 the valid entries. The invalid entries are not represented explicitly
2458 in the stream. The header format is:
2466 Writes to the fd create HPT entries starting at the index given in the
2467 header; first `n_valid' valid entries with contents from the data
2485 Creates an emulated device in the kernel. The file descriptor returned
2488 If the KVM_CREATE_DEVICE_TEST flag is set, only test whether the
2490 in the current vm).
2493 for specifying any behavior that is not implied by the device type
2512 sense when the device is in a different state)
2518 the "devices" directory. As with ONE_REG, the size of the data
2519 transferred is defined by the particular attribute.
2538 return indicates the attribute is implemented. It does not necessarily
2539 indicate that the attribute can be read or written in the device's
2550 EINVAL: the target is unknown, or the combination of features is invalid.
2553 This tells KVM what type of CPU to present to the guest, and what
2554 optional features it should have. This will cause a reset of the cpu
2562 after the vcpu has been run. This will reset the vcpu to its initial
2563 state. All calls to this function after the initial call must use the same
2567 - KVM_ARM_VCPU_POWER_OFF: Starts the CPU in a power-off state.
2568 Depends on KVM_CAP_ARM_PSCI. If not set, the CPU will be powered on
2570 - KVM_ARM_VCPU_EL1_32BIT: Starts the CPU in a 32bit mode.
2572 - KVM_ARM_VCPU_PSCI_0_2: Emulate PSCI v0.2 for the CPU.
2584 ENODEV: no preferred target available for the host
2592 the preferred target recommends setting these features, but this is
2608 E2BIG: the reg index list is too big to fit in the array specified by
2609 the user (the number required will be written into n).
2616 This ioctl returns the guest registers that are supported for the
2639 Specify a device address in the guest's physical address space where guests
2640 can access emulated or directly exposed devices, which the host kernel needs
2644 ARM/arm64 divides the id field into two parts, a device id and an
2645 address type id specific to the individual device.
2650 ARM/arm64 currently only require this when using the in-kernel GIC
2651 support for the hardware VGIC features, using KVM_ARM_DEVICE_VGIC_V2
2652 as the device id. When setting the base address for the guest's
2653 mapping of the VGIC virtual CPU and distributor interface, the ioctl
2655 KVM_RUN on any of the VCPUs. Calling this ioctl twice for any of the
2658 Note, this IOCTL is deprecated and the more flexible SET/GET_DEVICE_ATTR API
2671 service in order to allow it to be handled in the kernel. The
2672 argument struct gives the name of the service, which must be the name
2673 of a service that has a kernel-side implementation. If the token
2675 subsequent RTAS calls by the guest specifying that token will be
2676 handled by the kernel. If the token value is 0, then any token
2677 associated with the service will be forgotten, and subsequent RTAS
2678 calls by the guest for that service will be passed to userspace to be
2695 Set up the processor specific debug registers and configure vcpu for
2696 handling guest debug events. There are two parts to the structure, the
2697 first a control bitfield indicates the type of debug events to handle
2701 - KVM_GUESTDBG_SINGLESTEP: the next run should single-step
2703 The top 16 bits of the control field are architecture specific control
2704 flags which can include the following:
2714 correctly trapped and the KVM run loop exits at the breakpoint and not
2715 running off into the normal guest vector. For KVM_GUESTDBG_USE_HW_BP
2716 we need to ensure the guest vCPUs architecture specific registers are
2717 updated to the correct (supplied) values.
2719 The second part of the structure is architecture specific and
2722 For arm64 the number of debug registers is implementation defined and
2723 can be determined by querying the KVM_CAP_GUEST_DEBUG_HW_BPS and
2725 indicating the number of supported registers.
2727 When debug events exit the main run loop with the reason
2728 KVM_EXIT_DEBUG with the kvm_debug_exit_arch part of the kvm_run
2763 kvm.Userspace can use the information returned by this ioctl to query
2767 structure with the 'nent' field indicating the number of entries in
2768 the variable-size array 'entries'. If the number of entries is too low
2769 to describe the cpu capabilities, an error (E2BIG) is returned. If the
2770 number is too high, the 'nent' field is adjusted and an error (ENOMEM)
2771 is returned. If the number is just right, the 'nent' field is adjusted
2772 to the number of valid entries in the 'entries' array, which is then
2775 The entries returned are the set CPUID bits of the respective features
2776 which kvm emulates, as returned by the CPUID instruction, with unknown
2779 Features like x2apic, for example, may not be present in the host cpu
2785 function: the eax value used to obtain the entry
2786 index: the ecx value used to obtain the entry (for entries that are
2788 flags: an OR of zero or more of the following:
2790 if the index field is valid
2793 invocations; there will be several entries with the same function,
2797 the first entry to be read by a cpu
2798 eax, ebx, ecx, edx: the values returned by the cpuid instruction for
2809 > 0 if an exception occurred while walking the page tables
2811 Read or write data from/to the logical (virtual) memory of a VCPU.
2813 Parameters are specified via the following structure:
2816 __u64 gaddr; /* the guest address */
2821 __u8 ar; /* the access register number */
2825 The type of operation is specified in the "op" field. It is either
2828 KVM_S390_MEMOP_F_CHECK_ONLY flag can be set in the "flags" field to check
2829 whether the corresponding memory access would create an access exception
2830 (without touching the data in the memory at the destination). In case an
2831 access exception occurred while walking the MMU tables of the guest, the
2832 ioctl returns a positive error number to indicate the type of exception.
2833 This exception is also raised directly at the corresponding VCPU if the
2834 flag KVM_S390_MEMOP_F_INJECT_EXCEPTION is set in the "flags" field.
2836 The start address of the memory region has to be specified in the "gaddr"
2837 field, and the length of the region in the "size" field. "buf" is the buffer
2838 supplied by the userspace application where the read data should be written
2839 to for KVM_S390_MEMOP_LOGICAL_READ, or where the data that should be written
2841 when KVM_S390_MEMOP_F_CHECK_ONLY is specified. "ar" designates the access
2845 KVM with the currently defined set of flags.
2856 This ioctl is used to get guest storage key values on the s390
2857 architecture. The ioctl takes parameters via the kvm_s390_skeys struct.
2867 The start_gfn field is the number of the first guest frame whose storage keys
2870 The count field is the number of consecutive frames (starting from start_gfn)
2871 whose storage keys to get. The count field must be at least 1 and the maximum
2873 will cause the ioctl to return -EINVAL.
2875 The skeydata_addr field is the address to a buffer large enough to hold count
2876 bytes. This buffer will be filled with storage key data by the ioctl.
2886 This ioctl is used to set guest storage key values on the s390
2887 architecture. The ioctl takes parameters via the kvm_s390_skeys struct.
2890 The start_gfn field is the number of the first guest frame whose storage keys
2893 The count field is the number of consecutive frames (starting from start_gfn)
2894 whose storage keys to get. The count field must be at least 1 and the maximum
2896 will cause the ioctl to return -EINVAL.
2898 The skeydata_addr field is the address to a buffer containing count bytes of
2899 storage keys. Each byte in the buffer will be set as the storage key for a
2902 Note: If any architecturally invalid key value is found in the given data then
2903 the ioctl will return -EINVAL.
2916 than the maximum of VCPUs
2922 Allows to inject an interrupt to the guest.
2945 type can be one of the following:
2958 Note that the vcpu ioctl is asynchronous to vcpu execution.
2969 -EFAULT if the buffer address was invalid
2971 This ioctl allows userspace to retrieve the complete state of all currently
2973 and introspection. The parameter structure contains the address of a
2983 Userspace passes in the above struct and for each pending interrupt a
2984 struct kvm_s390_irq is copied to the provided buffer.
2986 If -ENOBUFS is returned the buffer provided was too small and userspace
2996 -EFAULT if the buffer address was invalid,
2999 errors occurring when actually injecting the
3002 This ioctl allows userspace to set the complete state of all cpu-local
3003 interrupts currently pending for the vcpu. It is intended for restoring
3014 for each interrupt to be injected into the guest.
3015 If one of the interrupts could not be injected for some reason the
3020 which is the maximum number of possibly pending cpu-local interrupts.
3030 Queues an SMI on the thread's vcpu.
3035 Application code obtains a pointer to the kvm_run structure by
3037 execution by changing fields in kvm_run prior to calling the KVM_RUN
3038 ioctl, and obtain information about the reason KVM_RUN returned by
3046 interrupts into the guest. Useful in conjunction with KVM_INTERRUPT.
3064 The value of the current interrupt flag. Only valid if in-kernel
3069 More architecture-specific flags detailing state of the VCPU that may
3070 affect the device's behavior. The only currently defined flag is
3071 KVM_RUN_X86_SMM, which is valid on x86 machines and is set if the
3077 The value of the cr8 register. Only valid if in-kernel local APIC is
3082 The value of the APIC BASE msr. Only valid if in-kernel local
3091 If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown
3100 If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due
3123 If exit_reason is KVM_EXIT_IO, then the vcpu has
3125 data_offset describes where the data is located (KVM_EXIT_IO_OUT) or
3126 where kvm expects application code to place the data for the next
3134 If the exit_reason is KVM_EXIT_DEBUG, then a vcpu is processing a debug event
3145 If exit_reason is KVM_EXIT_MMIO, then the vcpu has
3147 by kvm. The 'data' member contains the written data if 'is_write' is
3150 The 'data' member contains, in its first 'len' bytes, the value as it would
3151 appear if the VCPU performed a load or store of the appropriate width directly
3152 to the byte array.
3155 KVM_EXIT_EPR the corresponding
3157 has re-entered the kernel with KVM_RUN. The kernel side will first finish
3159 can re-enter the guest with an unmasked signal pending to complete
3213 resolved by the kernel.
3214 The program code and the translation exception code that were placed
3215 in the cpu's lowcore are presented here as defined by the z Architecture
3216 Principles of Operation Book in the Chapter for Dynamic Address Translation
3234 hypercalls and exit with this exit struct that contains all the guest gprs.
3236 If exit_reason is KVM_EXIT_OSI, then the vcpu has triggered such a hypercall.
3237 Userspace can now handle the hypercall and when it's done modify the gprs as
3238 necessary. Upon guest entry all guest GPRs will then be replaced by the values
3249 e.g. with the 'pseries' machine type in qemu. It occurs when the
3250 guest does a hypercall using the 'sc 1' instruction. The 'nr' field
3251 contains the hypercall number (from the guest R3), and 'args' contains
3252 the arguments (from the guest R4 - R12). Userspace should put the
3254 The possible hypercalls are defined in the Power Architecture Platform
3270 interrupt for the target subchannel has been dequeued and subchannel_id,
3271 subchannel_nr, io_int_parm and io_int_word contain the parameters for that
3279 On FSL BookE PowerPC chips, the interrupt controller has a fast patch
3280 interrupt acknowledge path to the core. When the core successfully
3281 delivers an interrupt, it automatically populates the EPR register with
3282 the interrupt vector number and acknowledges the interrupt inside
3283 the interrupt controller.
3285 In case the interrupt controller lives in user space, we need to do
3286 the interrupt acknowledge cycle through it to fetch the next to be
3290 external interrupt has just been delivered into the guest. User space
3291 should put the acknowledged interrupt vector into the 'epr' field.
3302 If exit_reason is KVM_EXIT_SYSTEM_EVENT then the vcpu has triggered
3305 HVC instruction based PSCI call from the vcpu. The 'type' field describes
3306 the system-level event type. The 'flags' field describes architecture
3307 specific flags for the system-level event.
3310 KVM_SYSTEM_EVENT_SHUTDOWN -- the guest has requested a shutdown of the
3312 this does not need to destroy the VM synchronously (ie it may call
3314 KVM_SYSTEM_EVENT_RESET -- the guest has requested a reset of the VM.
3315 As with SHUTDOWN, userspace can choose to ignore the request, or
3316 to schedule the reset to occur in the future and may call KVM_RUN again.
3317 KVM_SYSTEM_EVENT_CRASH -- the guest crash occurred and the guest
3319 to ignore the request, or to gather VM memory core dump and/or
3320 reset/shutdown of the VM.
3327 Indicates that the VCPU's in-kernel local APIC received an EOI for a
3328 level-triggered IOAPIC interrupt. This exit only triggers when the
3330 the userspace IOAPIC should process the EOI and retrigger the interrupt if
3331 it is still asserted. Vector is the LAPIC interrupt vector for which the
3334 /* Fix the size of the union. */
3340 * kvm_valid_regs specifies the register classes set by the host
3341 * kvm_dirty_regs specified the register classes dirtied by userspace
3342 * struct kvm_sync_regs is architecture specific, as well as the
3354 avoid some system call overhead if userspace has to handle the exit.
3355 Userspace can query the validity of the structure by checking
3357 and usually define the validity of a groups of registers. (e.g. one bit
3360 Please note that the kernel is allowed to use the kvm_run structure as the
3361 primary storage for certain register types. Therefore, the kernel may use the
3362 values in kvm_run even if the corresponding bit in kvm_dirty_regs is not set.
3371 There are certain capabilities that change the behavior of the virtual CPU or
3372 the virtual machine when enabled. To enable them, please see section 4.37.
3373 Below you can find a list of capabilities and what their effect on the vCPU or
3374 the virtual machine is when enabling them.
3376 The following information is provided along with the description:
3383 Parameters: what parameters are accepted by the capability.
3385 Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL)
3397 be treated as normal system calls to be injected into the guest. OSI hypercalls
3399 between the guest and the host.
3412 done using the hypercall instruction "sc 1".
3414 It also sets the guest privilege level to "supervisor" mode. Usually the guest
3417 In addition to the above, it changes the semantics of SDR1. In this mode, the
3418 HTAB address part of SDR1 contains an HVA instead of a GPA, as PAPR keeps the
3419 HTAB invisible to the guest.
3428 Parameters: args[0] is the address of a struct kvm_config_tlb
3438 Configures the virtual CPU's TLB array, establishing a shared memory area
3441 safety mechanism, and should be set to the size in bytes of the memory that
3442 userspace has reserved for the array. It must be at least the size dictated
3445 While KVM_RUN is active, the shared region is under control of KVM. Its
3449 On return from KVM_RUN, the shared region will reflect the current state of
3450 the guest's TLB. If userspace makes any changes, it must call KVM_DIRTY_TLB
3458 - The array consists of all entries in the first TLB, followed by all
3459 entries in the second TLB.
3463 where "num_sets" is the tlb_sizes[] value divided by the tlb_ways[] value.
3464 - The tsize field of mas1 shall be set to 4K on TLB0, even though the
3476 TEST PENDING INTERRUPTION and the interrupt portion of TEST SUBCHANNEL are
3477 handled in-kernel, while the other I/O instructions are passed to userspace.
3482 Note that even though this capability is enabled per-vcpu, the complete
3489 Parameters: args[0] defines whether the proxy facility is active
3492 This capability enables or disables the delivery of interrupts through the
3495 When enabled (args[0] != 0), every time the guest gets an external interrupt
3497 to receive the topmost interrupt vector.
3506 Parameters: args[0] is the MPIC device fd
3507 args[1] is the MPIC CPU number for this vcpu
3509 This capability connects the vcpu to an in-kernel MPIC device.
3515 Parameters: args[0] is the XICS device fd
3516 args[1] is the XICS CPU number (server ID) for this vcpu
3518 This capability connects the vcpu to an in-kernel XICS device.
3526 This capability enables the in-kernel irqchip for s390. Please refer to
3535 This capability allows the use of the host Floating Point Unit by the guest. It
3536 allows the Config1.FP bit to be set to enable the FPU in the guest. Once this is
3537 done the KVM_REG_MIPS_FPR_* and KVM_REG_MIPS_FCR_* registers can be accessed
3538 (depending on the current guest FPU register mode), and the Status.FR,
3539 Config5.FRE bits are accessible via the KVM API and also from the guest,
3540 depending on them being supported by the FPU.
3548 This capability allows the use of the MIPS SIMD Architecture (MSA) by the guest.
3549 It allows the Config3.MSAP bit to be set to enable the use of MSA by the guest.
3550 Once this is done the KVM_REG_MIPS_VEC_* and KVM_REG_MIPS_MSA_* registers can be
3551 accessed, and the Config5.MSAEn bit is accessible via the KVM API and also from
3552 the guest.
3557 There are certain capabilities that change the behavior of the virtual
3559 you can find a list of capabilities and what their effect on the VM
3562 The following information is provided along with the description:
3567 Parameters: what parameters are accepted by the capability.
3569 Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL)
3576 Parameters: args[0] is the sPAPR hcall number
3580 get handled by the kernel or not. Enabling or disabling in-kernel
3581 handling of an hcall is effective across the VM. On creation, an
3584 before this capability was implemented. If disabled, the kernel will
3585 not to attempt to handle the hcall, but will always exit to userspace
3590 If the hcall number specified is not one that has an in-kernel
3591 implementation, the KVM_ENABLE_CAP ioctl will fail with an EINVAL
3601 in the kernel:
3610 Only privileged operation exceptions will be checked for in the kernel (or even
3611 in the hardware prior to interception). If this capability is not enabled, the
3620 Allows use of the vector registers introduced with z13 processor, and
3621 provides for the synchronization between host and user space. Will
3622 return -EINVAL if the machine does not support vectors.
3629 This capability allows post-handlers for the STSI instruction. After
3630 initial handling in the kernel, KVM exits to user space with
3658 Create a local apic for each processor in the kernel. This can be used
3659 instead of KVM_CREATE_IRQCHIP if the userspace VMM wishes to emulate the
3660 IOAPIC and PIC (and also the PIT, even though this has to be enabled
3665 used in the IRQ routing table. The first args[0] MSI routes are reserved
3666 for the IOAPIC pins. Whenever the LAPIC receives an EOI for these routes,
3669 Fails if VCPU has already been created, or if the irqchip is already in the
3677 features of the KVM implementation.
3684 available, means that that the kernel has an implementation of the
3686 If present, the kernel H_RANDOM handler can be enabled for guest use
3687 with the KVM_CAP_PPC_ENABLE_HCALL capability.