4.1 KVM_GET_API_VERSION¶

This identifies the API version as the stable kvm API. It is notexpected that this number will change. However, Linux 2.6.20 and2.6.21 report earlier versions; these are not documented and notsupported. Applications should refuse to run if KVM_GET_API_VERSIONreturns a value other than 12. If this check passes, all ioctlsdescribed as ‘basic’ will be available.

4.2 KVM_CREATE_VM¶

The new VM has no virtual cpus and no memory.You probably want to use 0 as machine type.

In order to create user controlled virtual machines on S390, checkKVM_CAP_S390_UCONTROL and use the flag KVM_VM_S390_UCONTROL asprivileged user (CAP_SYS_ADMIN).

To use hardware assisted virtualization on MIPS (VZ ASE) rather thanthe default trap & emulate implementation (which changes the virtualmemory layout to fit in user mode), check KVM_CAP_MIPS_VZ and use theflag KVM_VM_MIPS_VZ.

On arm64, the physical address size for a VM (IPA Size limit) is limitedto 40bits by default. The limit can be configured if the host supports theextension KVM_CAP_ARM_VM_IPA_SIZE. When supported, useKVM_VM_TYPE_ARM_IPA_SIZE(IPA_Bits) to set the size in the machine typeidentifier, where IPA_Bits is the maximum width of any physicaladdress used by the VM. The IPA_Bits is encoded in bits[7-0] of themachine type identifier.

e.g, to configure a guest to use 48bit physical address size:

vm_fd = ioctl(dev_fd, KVM_CREATE_VM, KVM_VM_TYPE_ARM_IPA_SIZE(48));

The requested size (IPA_Bits) must be:

0	Implies default size, 40bits (for backward compatibility)
N	Implies N bits, where N is a positive integer such that,32 <= N <= Host_IPA_Limit

Host_IPA_Limit is the maximum possible value for IPA_Bits on the host andis dependent on the CPU capability and the kernel configuration. The limit canbe retrieved using KVM_CAP_ARM_VM_IPA_SIZE of the KVM_CHECK_EXTENSIONioctl() at run-time.

Please note that configuring the IPA size does not affect the capabilityexposed by the guest CPUs in ID_AA64MMFR0_EL1[PARange]. It only affectssize of the address translated by the stage2 level (guest physical tohost physical address translations).

4.3 KVM_GET_MSR_INDEX_LIST, KVM_GET_MSR_FEATURE_INDEX_LIST¶

Errors:

EFAULT	the msr index list cannot be read from or written to
E2BIG	the msr index list is to be to fit in the array specified bythe user.

struct kvm_msr_list {      __u32 nmsrs; /* number of msrs in entries */      __u32 indices[0];};

The user fills in the size of the indices array in nmsrs, and in returnkvm adjusts nmsrs to reflect the actual number of msrs and fills in theindices array with their numbers.

KVM_GET_MSR_INDEX_LIST returns the guest msrs that are supported. The listvaries by kvm version and host processor, but does not change otherwise.

Note: if kvm indicates supports MCE (KVM_CAP_MCE), then the MCE bank MSRs arenot returned in the MSR list, as different vcpus can have a different numberof banks, as set via the KVM_X86_SETUP_MCE ioctl.

KVM_GET_MSR_FEATURE_INDEX_LIST returns the list of MSRs that can be passedto the KVM_GET_MSRS system ioctl. This lets userspace probe host capabilitiesand processor features that are exposed via MSRs (e.g., VMX capabilities).This list also varies by kvm version and host processor, but does not changeotherwise.

4.4 KVM_CHECK_EXTENSION¶

The API allows the application to query about extensions to the corekvm API. Userspace passes an extension identifier (an integer) andreceives an integer that describes the extension availability.Generally 0 means no and 1 means yes, but some extensions may reportadditional information in the integer return value.

Based on their initialization different VMs may have different capabilities.It is thus encouraged to use the vm ioctl to query for capabilities (availablewith KVM_CAP_CHECK_EXTENSION_VM on the vm fd)

4.5 KVM_GET_VCPU_MMAP_SIZE¶

The KVM_RUN ioctl (cf.) communicates with userspace via a sharedmemory region. This ioctl returns the size of that region. See theKVM_RUN documentation for details.

4.6 KVM_SET_MEMORY_REGION¶

This ioctl is obsolete and has been removed.

4.7 KVM_CREATE_VCPU¶

This API adds a vcpu to a virtual machine. No more than max_vcpus may be added.The vcpu id is an integer in the range [0, max_vcpu_id).

The recommended max_vcpus value can be retrieved using the KVM_CAP_NR_VCPUS ofthe KVM_CHECK_EXTENSION ioctl() at run-time.The maximum possible value for max_vcpus can be retrieved using theKVM_CAP_MAX_VCPUS of the KVM_CHECK_EXTENSION ioctl() at run-time.

If the KVM_CAP_NR_VCPUS does not exist, you should assume that max_vcpus is 4cpus max.If the KVM_CAP_MAX_VCPUS does not exist, you should assume that max_vcpus issame as the value returned from KVM_CAP_NR_VCPUS.

The maximum possible value for max_vcpu_id can be retrieved using theKVM_CAP_MAX_VCPU_ID of the KVM_CHECK_EXTENSION ioctl() at run-time.

If the KVM_CAP_MAX_VCPU_ID does not exist, you should assume that max_vcpu_idis the same as the value returned from KVM_CAP_MAX_VCPUS.

On powerpc using book3s_hv mode, the vcpus are mapped onto virtualthreads in one or more virtual CPU cores. (This is because thehardware requires all the hardware threads in a CPU core to be in thesame partition.) The KVM_CAP_PPC_SMT capability indicates the numberof vcpus per virtual core (vcore). The vcore id is obtained bydividing the vcpu id by the number of vcpus per vcore. The vcpus in agiven vcore will always be in the same physical core as each other(though that might be a different physical core from time to time).Userspace can control the threading (SMT) mode of the guest by itsallocation of vcpu ids. For example, if userspace wantssingle-threaded guest vcpus, it should make all vcpu ids be a multipleof the number of vcpus per vcore.

For virtual cpus that have been created with S390 user controlled virtualmachines, the resulting vcpu fd can be memory mapped at page offsetKVM_S390_SIE_PAGE_OFFSET in order to obtain a memory map of the virtualcpu’s hardware control block.

4.8 KVM_GET_DIRTY_LOG (vm ioctl)¶

/* for KVM_GET_DIRTY_LOG */struct kvm_dirty_log {      __u32 slot;      __u32 padding;      union {              void __user *dirty_bitmap; /* one bit per page */              __u64 padding;      };};

Given a memory slot, return a bitmap containing any pages dirtiedsince the last call to this ioctl. Bit 0 is the first page in thememory slot. Ensure the entire structure is cleared to avoid paddingissues.

If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 specifiesthe address space for which you want to return the dirty bitmap.They must be less than the value that KVM_CHECK_EXTENSION returns forthe KVM_CAP_MULTI_ADDRESS_SPACE capability.

The bits in the dirty bitmap are cleared before the ioctl returns, unlessKVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 is enabled. For more information,see the description of the capability.

4.9 KVM_SET_MEMORY_ALIAS¶

This ioctl is obsolete and has been removed.

4.10 KVM_RUN¶

Errors:

EINTR

an unmasked signal is pending

This ioctl is used to run a guest virtual cpu. While there are noexplicit parameters, there is an implicit parameter block that can beobtained by mmap()ing the vcpu fd at offset 0, with the size given byKVM_GET_VCPU_MMAP_SIZE. The parameter block is formatted as a ‘structkvm_run’ (see below).

4.11 KVM_GET_REGS¶

Reads the general purpose registers from the vcpu.

/* x86 */struct kvm_regs {      /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */      __u64 rax, rbx, rcx, rdx;      __u64 rsi, rdi, rsp, rbp;      __u64 r8,  r9,  r10, r11;      __u64 r12, r13, r14, r15;      __u64 rip, rflags;};/* mips */struct kvm_regs {      /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */      __u64 gpr[32];      __u64 hi;      __u64 lo;      __u64 pc;};

4.12 KVM_SET_REGS¶

Writes the general purpose registers into the vcpu.

See KVM_GET_REGS for the data structure.

4.13 KVM_GET_SREGS¶

Reads special registers from the vcpu.

/* x86 */struct kvm_sregs {      struct kvm_segment cs, ds, es, fs, gs, ss;      struct kvm_segment tr, ldt;      struct kvm_dtable gdt, idt;      __u64 cr0, cr2, cr3, cr4, cr8;      __u64 efer;      __u64 apic_base;      __u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64];};/* ppc -- see arch/powerpc/include/uapi/asm/kvm.h */

interrupt_bitmap is a bitmap of pending external interrupts. At mostone bit may be set. This interrupt has been acknowledged by the APICbut not yet injected into the cpu core.

4.14 KVM_SET_SREGS¶

Writes special registers into the vcpu. See KVM_GET_SREGS for thedata structures.

4.15 KVM_TRANSLATE¶

Translates a virtual address according to the vcpu’s current addresstranslation mode.

struct kvm_translation {      /* in */      __u64 linear_address;      /* out */      __u64 physical_address;      __u8  valid;      __u8  writeable;      __u8  usermode;      __u8  pad[5];};

4.16 KVM_INTERRUPT¶

Queues a hardware interrupt vector to be injected.

/* for KVM_INTERRUPT */struct kvm_interrupt {      /* in */      __u32 irq;};

4.17 KVM_DEBUG_GUEST¶

Support for this has been removed. Use KVM_SET_GUEST_DEBUG instead.

4.18 KVM_GET_MSRS¶

When used as a system ioctl:Reads the values of MSR-based features that are available for the VM. Thisis similar to KVM_GET_SUPPORTED_CPUID, but it returns MSR indices and values.The list of msr-based features can be obtained using KVM_GET_MSR_FEATURE_INDEX_LISTin a system ioctl.

When used as a vcpu ioctl:Reads model-specific registers from the vcpu. Supported msr indices canbe obtained using KVM_GET_MSR_INDEX_LIST in a system ioctl.

struct kvm_msrs {      __u32 nmsrs; /* number of msrs in entries */      __u32 pad;      struct kvm_msr_entry entries[0];};struct kvm_msr_entry {      __u32 index;      __u32 reserved;      __u64 data;};

Application code should set the ‘nmsrs’ member (which indicates thesize of the entries array) and the ‘index’ member of each array entry.kvm will fill in the ‘data’ member.

4.19 KVM_SET_MSRS¶

Writes model-specific registers to the vcpu. See KVM_GET_MSRS for thedata structures.

Application code should set the ‘nmsrs’ member (which indicates thesize of the entries array), and the ‘index’ and ‘data’ members of eacharray entry.

It tries to set the MSRs in array entries[] one by one. If setting an MSRfails, e.g., due to setting reserved bits, the MSR isn’t supported/emulatedby KVM, etc…, it stops processing the MSR list and returns the number ofMSRs that have been set successfully.

4.20 KVM_SET_CPUID¶

Defines the vcpu responses to the cpuid instruction. Applicationsshould use the KVM_SET_CPUID2 ioctl if available.

Note, when this IOCTL fails, KVM gives no guarantees that previous valid CPUIDconfiguration (if there is) is not corrupted. Userspace can get a copy of theresulting CPUID configuration through KVM_GET_CPUID2 in case.

struct kvm_cpuid_entry {      __u32 function;      __u32 eax;      __u32 ebx;      __u32 ecx;      __u32 edx;      __u32 padding;};/* for KVM_SET_CPUID */struct kvm_cpuid {      __u32 nent;      __u32 padding;      struct kvm_cpuid_entry entries[0];};

4.21 KVM_SET_SIGNAL_MASK¶

Defines which signals are blocked during execution of KVM_RUN. Thissignal mask temporarily overrides the threads signal mask. Anyunblocked signal received (except SIGKILL and SIGSTOP, which retaintheir traditional behaviour) will cause KVM_RUN to return with -EINTR.

Note the signal will only be delivered if not blocked by the originalsignal mask.

/* for KVM_SET_SIGNAL_MASK */struct kvm_signal_mask {      __u32 len;      __u8  sigset[0];};

4.22 KVM_GET_FPU¶

Reads the floating point state from the vcpu.

/* for KVM_GET_FPU and KVM_SET_FPU */struct kvm_fpu {      __u8  fpr[8][16];      __u16 fcw;      __u16 fsw;      __u8  ftwx;  /* in fxsave format */      __u8  pad1;      __u16 last_opcode;      __u64 last_ip;      __u64 last_dp;      __u8  xmm[16][16];      __u32 mxcsr;      __u32 pad2;};

4.23 KVM_SET_FPU¶

Writes the floating point state to the vcpu.

/* for KVM_GET_FPU and KVM_SET_FPU */struct kvm_fpu {      __u8  fpr[8][16];      __u16 fcw;      __u16 fsw;      __u8  ftwx;  /* in fxsave format */      __u8  pad1;      __u16 last_opcode;      __u64 last_ip;      __u64 last_dp;      __u8  xmm[16][16];      __u32 mxcsr;      __u32 pad2;};

4.24 KVM_CREATE_IRQCHIP¶

Creates an interrupt controller model in the kernel.On x86, creates a virtual ioapic, a virtual PIC (two PICs, nested), and sets upfuture vcpus to have a local APIC. IRQ routing for GSIs 0-15 is set to bothPIC and IOAPIC; GSI 16-23 only go to the IOAPIC.On ARM/arm64, a GICv2 is created. Any other GIC versions require the usage ofKVM_CREATE_DEVICE, which also supports creating a GICv2. UsingKVM_CREATE_DEVICE is preferred over KVM_CREATE_IRQCHIP for GICv2.On s390, a dummy irq routing table is created.

Note that on s390 the KVM_CAP_S390_IRQCHIP vm capability needs to be enabledbefore KVM_CREATE_IRQCHIP can be used.

4.25 KVM_IRQ_LINE¶

Sets the level of a GSI input to the interrupt controller model in the kernel.On some architectures it is required that an interrupt controller model hasbeen previously created with KVM_CREATE_IRQCHIP. Note that edge-triggeredinterrupts require the level to be set to 1 and then back to 0.

On real hardware, interrupt pins can be active-low or active-high. Thisdoes not matter for the level field of struct kvm_irq_level: 1 alwaysmeans active (asserted), 0 means inactive (deasserted).

x86 allows the operating system to program the interrupt polarity(active-low/active-high) for level-triggered interrupts, and KVM usedto consider the polarity. However, due to bitrot in the handling ofactive-low interrupts, the above convention is now valid on x86 too.This is signaled by KVM_CAP_X86_IOAPIC_POLARITY_IGNORED. Userspaceshould not present interrupts to the guest as active-low unless thiscapability is present (or unless it is not using the in-kernel irqchip,of course).

ARM/arm64 can signal an interrupt either at the CPU level, or at thein-kernel irqchip (GIC), and for in-kernel irqchip can tell the GIC touse PPIs designated for specific cpus. The irq field is interpretedlike this:

bits:  |  31 ... 28  | 27 ... 24 | 23  ... 16 | 15 ... 0 |field: | vcpu2_index | irq_type  | vcpu_index |  irq_id  |

The irq_type field has the following values:

• irq_type[0]:

  out-of-kernel GIC: irq_id 0 is IRQ, irq_id 1 is FIQ

• irq_type[1]:

  in-kernel GIC: SPI, irq_id between 32 and 1019 (incl.)(the vcpu_index field is ignored)

• irq_type[2]:

  in-kernel GIC: PPI, irq_id between 16 and 31 (incl.)

(The irq_id field thus corresponds nicely to the IRQ ID in the ARM GIC specs)

In both cases, level is used to assert/deassert the line.

When KVM_CAP_ARM_IRQ_LINE_LAYOUT_2 is supported, the target vcpu isidentified as (256 * vcpu2_index + vcpu_index). Otherwise, vcpu2_indexmust be zero.

Note that on arm/arm64, the KVM_CAP_IRQCHIP capability only conditionsinjection of interrupts for the in-kernel irqchip. KVM_IRQ_LINE can alwaysbe used for a userspace interrupt controller.

struct kvm_irq_level {      union {              __u32 irq;     /* GSI */              __s32 status;  /* not used for KVM_IRQ_LEVEL */      };      __u32 level;           /* 0 or 1 */};

4.26 KVM_GET_IRQCHIP¶

Reads the state of a kernel interrupt controller created withKVM_CREATE_IRQCHIP into a buffer provided by the caller.

struct kvm_irqchip {      __u32 chip_id;  /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */      __u32 pad;      union {              char dummy[512];  /* reserving space */              struct kvm_pic_state pic;              struct kvm_ioapic_state ioapic;      } chip;};

4.27 KVM_SET_IRQCHIP¶

Sets the state of a kernel interrupt controller created withKVM_CREATE_IRQCHIP from a buffer provided by the caller.

struct kvm_irqchip {      __u32 chip_id;  /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */      __u32 pad;      union {              char dummy[512];  /* reserving space */              struct kvm_pic_state pic;              struct kvm_ioapic_state ioapic;      } chip;};

4.28 KVM_XEN_HVM_CONFIG¶

Sets the MSR that the Xen HVM guest uses to initialize its hypercallpage, and provides the starting address and size of the hypercallblobs in userspace. When the guest writes the MSR, kvm copies onepage of a blob (32- or 64-bit, depending on the vcpu mode) to guestmemory.

struct kvm_xen_hvm_config {      __u32 flags;      __u32 msr;      __u64 blob_addr_32;      __u64 blob_addr_64;      __u8 blob_size_32;      __u8 blob_size_64;      __u8 pad2[30];};

4.29 KVM_GET_CLOCK¶

Gets the current timestamp of kvmclock as seen by the current guest. Inconjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenariossuch as migration.

When KVM_CAP_ADJUST_CLOCK is passed to KVM_CHECK_EXTENSION, it returns theset of bits that KVM can return in struct kvm_clock_data’s flag member.

The only flag defined now is KVM_CLOCK_TSC_STABLE. If set, the returnedvalue is the exact kvmclock value seen by all VCPUs at the instantwhen KVM_GET_CLOCK was called. If clear, the returned value is simplyCLOCK_MONOTONIC plus a constant offset; the offset can be modifiedwith KVM_SET_CLOCK. KVM will try to make all VCPUs follow this clock,but the exact value read by each VCPU could differ, because the hostTSC is not stable.

struct kvm_clock_data {      __u64 clock;  /* kvmclock current value */      __u32 flags;      __u32 pad[9];};

4.30 KVM_SET_CLOCK¶

Sets the current timestamp of kvmclock to the value specified in its parameter.In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenariossuch as migration.

struct kvm_clock_data {      __u64 clock;  /* kvmclock current value */      __u32 flags;      __u32 pad[9];};

4.31 KVM_GET_VCPU_EVENTS¶

struct kvm_vcpu_events {      struct {              __u8 injected;              __u8 nr;              __u8 has_error_code;              __u8 pending;              __u32 error_code;      } exception;      struct {              __u8 injected;              __u8 nr;              __u8 soft;              __u8 shadow;      } interrupt;      struct {              __u8 injected;              __u8 pending;              __u8 masked;              __u8 pad;      } nmi;      __u32 sipi_vector;      __u32 flags;      struct {              __u8 smm;              __u8 pending;              __u8 smm_inside_nmi;              __u8 latched_init;      } smi;      __u8 reserved[27];      __u8 exception_has_payload;      __u64 exception_payload;};

struct kvm_vcpu_events {      struct {              __u8 serror_pending;              __u8 serror_has_esr;              __u8 ext_dabt_pending;              /* Align it to 8 bytes */              __u8 pad[5];              __u64 serror_esr;      } exception;      __u32 reserved[12];};

4.32 KVM_SET_VCPU_EVENTS¶

4.33 KVM_GET_DEBUGREGS¶

Reads debug registers from the vcpu.

struct kvm_debugregs {      __u64 db[4];      __u64 dr6;      __u64 dr7;      __u64 flags;      __u64 reserved[9];};

4.34 KVM_SET_DEBUGREGS¶

Writes debug registers into the vcpu.

See KVM_GET_DEBUGREGS for the data structure. The flags field is unusedyet and must be cleared on entry.

4.35 KVM_SET_USER_MEMORY_REGION¶

struct kvm_userspace_memory_region {      __u32 slot;      __u32 flags;      __u64 guest_phys_addr;      __u64 memory_size; /* bytes */      __u64 userspace_addr; /* start of the userspace allocated memory */};/* for kvm_memory_region::flags */#define KVM_MEM_LOG_DIRTY_PAGES       (1UL << 0)#define KVM_MEM_READONLY      (1UL << 1)

This ioctl allows the user to create, modify or delete a guest physicalmemory slot. Bits 0-15 of “slot” specify the slot id and this valueshould be less than the maximum number of user memory slots supported perVM. The maximum allowed slots can be queried using KVM_CAP_NR_MEMSLOTS.Slots may not overlap in guest physical address space.

If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 of “slot”specifies the address space which is being modified. They must beless than the value that KVM_CHECK_EXTENSION returns for theKVM_CAP_MULTI_ADDRESS_SPACE capability. Slots in separate address spacesare unrelated; the restriction on overlapping slots only applies withineach address space.

Deleting a slot is done by passing zero for memory_size. When changingan existing slot, it may be moved in the guest physical memory space,or its flags may be modified, but it may not be resized.

Memory for the region is taken starting at the address denoted by thefield userspace_addr, which must point at user addressable memory forthe entire memory slot size. Any object may back this memory, includinganonymous memory, ordinary files, and hugetlbfs.

It is recommended that the lower 21 bits of guest_phys_addr and userspace_addrbe identical. This allows large pages in the guest to be backed by largepages in the host.

The flags field supports two flags: KVM_MEM_LOG_DIRTY_PAGES andKVM_MEM_READONLY. The former can be set to instruct KVM to keep track ofwrites to memory within the slot. See KVM_GET_DIRTY_LOG ioctl to know how touse it. The latter can be set, if KVM_CAP_READONLY_MEM capability allows it,to make a new slot read-only. In this case, writes to this memory will beposted to userspace as KVM_EXIT_MMIO exits.

When the KVM_CAP_SYNC_MMU capability is available, changes in the backing ofthe memory region are automatically reflected into the guest. For example, anmmap() that affects the region will be made visible immediately. Anotherexample is madvise(MADV_DROP).

It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl.The KVM_SET_MEMORY_REGION does not allow fine grained control over memoryallocation and is deprecated.

4.36 KVM_SET_TSS_ADDR¶

This ioctl defines the physical address of a three-page region in the guestphysical address space. The region must be within the first 4GB of theguest physical address space and must not conflict with any memory slotor any mmio address. The guest may malfunction if it accesses this memoryregion.

This ioctl is required on Intel-based hosts. This is needed on Intel hardwarebecause of a quirk in the virtualization implementation (see the internalsdocumentation when it pops into existence).

4.37 KVM_ENABLE_CAP¶

On systems that do not support this ioctl, it always fails. On systems thatdo support it, it only works for extensions that are supported for enablement.

To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl shouldbe used.

struct kvm_enable_cap {     /* in */     __u32 cap;

The capability that is supposed to get enabled.

__u32 flags;

A bitfield indicating future enhancements. Has to be 0 for now.

__u64 args[4];

Arguments for enabling a feature. If a feature needs initial values tofunction properly, this is the place to put them.

     __u8  pad[64];};

The vcpu ioctl should be used for vcpu-specific capabilities, the vm ioctlfor vm-wide capabilities.

4.38 KVM_GET_MP_STATE¶

struct kvm_mp_state {      __u32 mp_state;};

Returns the vcpu’s current “multiprocessing state” (though also valid onuniprocessor guests).

Possible values are:

KVM_MP_STATE_RUNNABLE	the vcpu is currently running [x86,arm/arm64]
KVM_MP_STATE_UNINITIALIZED	the vcpu is an application processor (AP)which has not yet received an INIT signal [x86]
KVM_MP_STATE_INIT_RECEIVED	the vcpu has received an INIT signal, and isnow ready for a SIPI [x86]
KVM_MP_STATE_HALTED	the vcpu has executed a HLT instruction andis waiting for an interrupt [x86]
KVM_MP_STATE_SIPI_RECEIVED	the vcpu has just received a SIPI (vectoraccessible via KVM_GET_VCPU_EVENTS) [x86]
KVM_MP_STATE_STOPPED	the vcpu is stopped [s390,arm/arm64]
KVM_MP_STATE_CHECK_STOP	the vcpu is in a special error state [s390]
KVM_MP_STATE_OPERATING	the vcpu is operating (running or halted)[s390]
KVM_MP_STATE_LOAD	the vcpu is in a special load/startup state[s390]

On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without anin-kernel irqchip, the multiprocessing state must be maintained by userspace onthese architectures.

4.39 KVM_SET_MP_STATE¶

Sets the vcpu’s current “multiprocessing state”; see KVM_GET_MP_STATE forarguments.

On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without anin-kernel irqchip, the multiprocessing state must be maintained by userspace onthese architectures.

4.40 KVM_SET_IDENTITY_MAP_ADDR¶

This ioctl defines the physical address of a one-page region in the guestphysical address space. The region must be within the first 4GB of theguest physical address space and must not conflict with any memory slotor any mmio address. The guest may malfunction if it accesses this memoryregion.

Setting the address to 0 will result in resetting the address to its default(0xfffbc000).

This ioctl is required on Intel-based hosts. This is needed on Intel hardwarebecause of a quirk in the virtualization implementation (see the internalsdocumentation when it pops into existence).

Fails if any VCPU has already been created.

4.41 KVM_SET_BOOT_CPU_ID¶

Define which vcpu is the Bootstrap Processor (BSP). Values are the sameas the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the defaultis vcpu 0.

4.42 KVM_GET_XSAVE¶

struct kvm_xsave {      __u32 region[1024];};

This ioctl would copy current vcpu’s xsave struct to the userspace.

4.43 KVM_SET_XSAVE¶

struct kvm_xsave {      __u32 region[1024];};

This ioctl would copy userspace’s xsave struct to the kernel.

4.44 KVM_GET_XCRS¶

struct kvm_xcr {      __u32 xcr;      __u32 reserved;      __u64 value;};struct kvm_xcrs {      __u32 nr_xcrs;      __u32 flags;      struct kvm_xcr xcrs[KVM_MAX_XCRS];      __u64 padding[16];};

This ioctl would copy current vcpu’s xcrs to the userspace.

4.45 KVM_SET_XCRS¶

struct kvm_xcr {      __u32 xcr;      __u32 reserved;      __u64 value;};struct kvm_xcrs {      __u32 nr_xcrs;      __u32 flags;      struct kvm_xcr xcrs[KVM_MAX_XCRS];      __u64 padding[16];};

This ioctl would set vcpu’s xcr to the value userspace specified.

4.46 KVM_GET_SUPPORTED_CPUID¶

struct kvm_cpuid2 {      __u32 nent;      __u32 padding;      struct kvm_cpuid_entry2 entries[0];};#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX               BIT(0)#define KVM_CPUID_FLAG_STATEFUL_FUNC          BIT(1) /* deprecated */#define KVM_CPUID_FLAG_STATE_READ_NEXT                BIT(2) /* deprecated */struct kvm_cpuid_entry2 {      __u32 function;      __u32 index;      __u32 flags;      __u32 eax;      __u32 ebx;      __u32 ecx;      __u32 edx;      __u32 padding[3];};

This ioctl returns x86 cpuid features which are supported by both thehardware and kvm in its default configuration. Userspace can use theinformation returned by this ioctl to construct cpuid information (forKVM_SET_CPUID2) that is consistent with hardware, kernel, anduserspace capabilities, and with user requirements (for example, theuser may wish to constrain cpuid to emulate older hardware, or forfeature consistency across a cluster).

Note that certain capabilities, such as KVM_CAP_X86_DISABLE_EXITS, mayexpose cpuid features (e.g. MONITOR) which are not supported by kvm inits default configuration. If userspace enables such capabilities, itis responsible for modifying the results of this ioctl appropriately.

Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structurewith the ‘nent’ field indicating the number of entries in the variable-sizearray ‘entries’. If the number of entries is too low to describe the cpucapabilities, an error (E2BIG) is returned. If the number is too high,the ‘nent’ field is adjusted and an error (ENOMEM) is returned. If thenumber is just right, the ‘nent’ field is adjusted to the number of validentries in the ‘entries’ array, which is then filled.

The entries returned are the host cpuid as returned by the cpuid instruction,with unknown or unsupported features masked out. Some features (for example,x2apic), may not be present in the host cpu, but are exposed by kvm if it canemulate them efficiently. The fields in each entry are defined as follows:

function:

the eax value used to obtain the entry

index:

the ecx value used to obtain the entry (for entries that areaffected by ecx)

flags:

an OR of zero or more of the following:

KVM_CPUID_FLAG_SIGNIFCANT_INDEX:

if the index field is valid

eax, ebx, ecx, edx:

the values returned by the cpuid instruction forthis function/index combination

The TSC deadline timer feature (CPUID leaf 1, ecx[24]) is always returnedas false, since the feature depends on KVM_CREATE_IRQCHIP for local APICsupport. Instead it is reported via:

ioctl(KVM_CHECK_EXTENSION, KVM_CAP_TSC_DEADLINE_TIMER)

if that returns true and you use KVM_CREATE_IRQCHIP, or if you emulate thefeature in userspace, then you can enable the feature for KVM_SET_CPUID2.

4.47 KVM_PPC_GET_PVINFO¶

struct kvm_ppc_pvinfo {      __u32 flags;      __u32 hcall[4];      __u8  pad[108];};

This ioctl fetches PV specific information that need to be passed to the guestusing the device tree or other means from vm context.

The hcall array defines 4 instructions that make up a hypercall.

If any additional field gets added to this structure later on, a bit for thatadditional piece of information will be set in the flags bitmap.

The flags bitmap is defined as:

/* the host supports the ePAPR idle hcall#define KVM_PPC_PVINFO_FLAGS_EV_IDLE   (1<<0)

4.52 KVM_SET_GSI_ROUTING¶

Sets the GSI routing table entries, overwriting any previously set entries.

On arm/arm64, GSI routing has the following limitation:

• GSI routing does not apply to KVM_IRQ_LINE but only to KVM_IRQFD.

struct kvm_irq_routing {      __u32 nr;      __u32 flags;      struct kvm_irq_routing_entry entries[0];};

No flags are specified so far, the corresponding field must be set to zero.

struct kvm_irq_routing_entry {      __u32 gsi;      __u32 type;      __u32 flags;      __u32 pad;      union {              struct kvm_irq_routing_irqchip irqchip;              struct kvm_irq_routing_msi msi;              struct kvm_irq_routing_s390_adapter adapter;              struct kvm_irq_routing_hv_sint hv_sint;              __u32 pad[8];      } u;};/* gsi routing entry types */#define KVM_IRQ_ROUTING_IRQCHIP 1#define KVM_IRQ_ROUTING_MSI 2#define KVM_IRQ_ROUTING_S390_ADAPTER 3#define KVM_IRQ_ROUTING_HV_SINT 4

flags:

• KVM_MSI_VALID_DEVID: used along with KVM_IRQ_ROUTING_MSI routing entrytype, specifies that the devid field contains a valid value. The per-VMKVM_CAP_MSI_DEVID capability advertises the requirement to providethe device ID. If this capability is not available, userspace shouldnever set the KVM_MSI_VALID_DEVID flag as the ioctl might fail.
• zero otherwise

struct kvm_irq_routing_irqchip {      __u32 irqchip;      __u32 pin;};struct kvm_irq_routing_msi {      __u32 address_lo;      __u32 address_hi;      __u32 data;      union {              __u32 pad;              __u32 devid;      };};

If KVM_MSI_VALID_DEVID is set, devid contains a unique device identifierfor the device that wrote the MSI message. For PCI, this is usually aBFD identifier in the lower 16 bits.

On x86, address_hi is ignored unless the KVM_X2APIC_API_USE_32BIT_IDSfeature of KVM_CAP_X2APIC_API capability is enabled. If it is enabled,address_hi bits 31-8 provide bits 31-8 of the destination id. Bits 7-0 ofaddress_hi must be zero.

struct kvm_irq_routing_s390_adapter {      __u64 ind_addr;      __u64 summary_addr;      __u64 ind_offset;      __u32 summary_offset;      __u32 adapter_id;};struct kvm_irq_routing_hv_sint {      __u32 vcpu;      __u32 sint;};

4.55 KVM_SET_TSC_KHZ¶

Specifies the tsc frequency for the virtual machine. The unit of thefrequency is KHz.

4.56 KVM_GET_TSC_KHZ¶

Returns the tsc frequency of the guest. The unit of the return value isKHz. If the host has unstable tsc this ioctl returns -EIO instead as anerror.

4.57 KVM_GET_LAPIC¶

#define KVM_APIC_REG_SIZE 0x400struct kvm_lapic_state {      char regs[KVM_APIC_REG_SIZE];};

Reads the Local APIC registers and copies them into the input argument. Thedata format and layout are the same as documented in the architecture manual.

If KVM_X2APIC_API_USE_32BIT_IDS feature of KVM_CAP_X2APIC_API isenabled, then the format of APIC_ID register depends on the APIC mode(reported by MSR_IA32_APICBASE) of its VCPU. x2APIC stores APIC ID inthe APIC_ID register (bytes 32-35). xAPIC only allows an 8-bit APIC IDwhich is stored in bits 31-24 of the APIC register, or equivalently inbyte 35 of struct kvm_lapic_state’s regs field. KVM_GET_LAPIC must thenbe called after MSR_IA32_APICBASE has been set with KVM_SET_MSR.

If KVM_X2APIC_API_USE_32BIT_IDS feature is disabled, struct kvm_lapic_statealways uses xAPIC format.

4.58 KVM_SET_LAPIC¶

#define KVM_APIC_REG_SIZE 0x400struct kvm_lapic_state {      char regs[KVM_APIC_REG_SIZE];};

Copies the input argument into the Local APIC registers. The data formatand layout are the same as documented in the architecture manual.

The format of the APIC ID register (bytes 32-35 of struct kvm_lapic_state’sregs field) depends on the state of the KVM_CAP_X2APIC_API capability.See the note in KVM_GET_LAPIC.

4.59 KVM_IOEVENTFD¶

This ioctl attaches or detaches an ioeventfd to a legal pio/mmio addresswithin the guest. A guest write in the registered address will signal theprovided event instead of triggering an exit.

struct kvm_ioeventfd {      __u64 datamatch;      __u64 addr;        /* legal pio/mmio address */      __u32 len;         /* 0, 1, 2, 4, or 8 bytes    */      __s32 fd;      __u32 flags;      __u8  pad[36];};

For the special case of virtio-ccw devices on s390, the ioevent is matchedto a subchannel/virtqueue tuple instead.

The following flags are defined:

#define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch)#define KVM_IOEVENTFD_FLAG_PIO       (1 << kvm_ioeventfd_flag_nr_pio)#define KVM_IOEVENTFD_FLAG_DEASSIGN  (1 << kvm_ioeventfd_flag_nr_deassign)#define KVM_IOEVENTFD_FLAG_VIRTIO_CCW_NOTIFY \      (1 << kvm_ioeventfd_flag_nr_virtio_ccw_notify)

If datamatch flag is set, the event will be signaled only if the written valueto the registered address is equal to datamatch in struct kvm_ioeventfd.

For virtio-ccw devices, addr contains the subchannel id and datamatch thevirtqueue index.

With KVM_CAP_IOEVENTFD_ANY_LENGTH, a zero length ioeventfd is allowed, andthe kernel will ignore the length of guest write and may get a faster vmexit.The speedup may only apply to specific architectures, but the ioeventfd willwork anyway.

4.60 KVM_DIRTY_TLB¶

struct kvm_dirty_tlb {      __u64 bitmap;      __u32 num_dirty;};

This must be called whenever userspace has changed an entry in the sharedTLB, prior to calling KVM_RUN on the associated vcpu.

The “bitmap” field is the userspace address of an array. This arrayconsists of a number of bits, equal to the total number of TLB entries asdetermined by the last successful call to KVM_CONFIG_TLB, rounded up to thenearest multiple of 64.

Each bit corresponds to one TLB entry, ordered the same as in the shared TLBarray.

The array is little-endian: the bit 0 is the least significant bit of thefirst byte, bit 8 is the least significant bit of the second byte, etc.This avoids any complications with differing word sizes.

The “num_dirty” field is a performance hint for KVM to determine whether itshould skip processing the bitmap and just invalidate everything. It mustbe set to the number of set bits in the bitmap.

4.62 KVM_CREATE_SPAPR_TCE¶

This creates a virtual TCE (translation control entry) table, whichis an IOMMU for PAPR-style virtual I/O. It is used to translatelogical addresses used in virtual I/O into guest physical addresses,and provides a scatter/gather capability for PAPR virtual I/O.

/* for KVM_CAP_SPAPR_TCE */struct kvm_create_spapr_tce {      __u64 liobn;      __u32 window_size;};

The liobn field gives the logical IO bus number for which to create aTCE table. The window_size field specifies the size of the DMA windowwhich this TCE table will translate - the table will contain one 64bit TCE entry for every 4kiB of the DMA window.

When the guest issues an H_PUT_TCE hcall on a liobn for which a TCEtable has been created using this ioctl(), the kernel will handle itin real mode, updating the TCE table. H_PUT_TCE calls for otherliobns will cause a vm exit and must be handled by userspace.

The return value is a file descriptor which can be passed to mmap(2)to map the created TCE table into userspace. This lets userspace readthe entries written by kernel-handled H_PUT_TCE calls, and also letsuserspace update the TCE table directly which is useful in somecircumstances.

4.63 KVM_ALLOCATE_RMA¶

This allocates a Real Mode Area (RMA) from the pool allocated at boottime by the kernel. An RMA is a physically-contiguous, aligned regionof memory used on older POWER processors to provide the memory whichwill be accessed by real-mode (MMU off) accesses in a KVM guest.POWER processors support a set of sizes for the RMA that usuallyincludes 64MB, 128MB, 256MB and some larger powers of two.

/* for KVM_ALLOCATE_RMA */struct kvm_allocate_rma {      __u64 rma_size;};

The return value is a file descriptor which can be passed to mmap(2)to map the allocated RMA into userspace. The mapped area can then bepassed to the KVM_SET_USER_MEMORY_REGION ioctl to establish it as theRMA for a virtual machine. The size of the RMA in bytes (which isfixed at host kernel boot time) is returned in the rma_size field ofthe argument structure.

The KVM_CAP_PPC_RMA capability is 1 or 2 if the KVM_ALLOCATE_RMA ioctlis supported; 2 if the processor requires all virtual machines to havean RMA, or 1 if the processor can use an RMA but doesn’t require it,because it supports the Virtual RMA (VRMA) facility.

4.64 KVM_NMI¶

Queues an NMI on the thread’s vcpu. Note this is well defined onlywhen KVM_CREATE_IRQCHIP has not been called, since this is an interfacebetween the virtual cpu core and virtual local APIC. After KVM_CREATE_IRQCHIPhas been called, this interface is completely emulated within the kernel.

To use this to emulate the LINT1 input with KVM_CREATE_IRQCHIP, use thefollowing algorithm:

• pause the vcpu
• read the local APIC’s state (KVM_GET_LAPIC)
• check whether changing LINT1 will queue an NMI (see the LVT entry for LINT1)
• if so, issue KVM_NMI
• resume the vcpu

Some guests configure the LINT1 NMI input to cause a panic, aiding indebugging.

4.65 KVM_S390_UCAS_MAP¶

The parameter is defined like this:

struct kvm_s390_ucas_mapping {        __u64 user_addr;        __u64 vcpu_addr;        __u64 length;};

This ioctl maps the memory at “user_addr” with the length “length” tothe vcpu’s address space starting at “vcpu_addr”. All parameters need tobe aligned by 1 megabyte.

4.66 KVM_S390_UCAS_UNMAP¶

The parameter is defined like this:

struct kvm_s390_ucas_mapping {        __u64 user_addr;        __u64 vcpu_addr;        __u64 length;};

This ioctl unmaps the memory in the vcpu’s address space starting at“vcpu_addr” with the length “length”. The field “user_addr” is ignored.All parameters need to be aligned by 1 megabyte.

4.67 KVM_S390_VCPU_FAULT¶

This call creates a page table entry on the virtual cpu’s address space(for user controlled virtual machines) or the virtual machine’s addressspace (for regular virtual machines). This only works for minor faults,thus it’s recommended to access subject memory page via the user pagetable upfront. This is useful to handle validity intercepts for usercontrolled virtual machines to fault in the virtual cpu’s lowcore pagesprior to calling the KVM_RUN ioctl.

4.68 KVM_SET_ONE_REG¶

Errors:

ENOENT	no such register
EINVAL	invalid register ID, or no such register or used with VMs inprotected virtualization mode on s390
EPERM	(arm64) register access not allowed before vcpu finalization

(These error codes are indicative only: do not rely on a specific errorcode being returned in a specific situation.)

 struct kvm_one_reg {      __u64 id;      __u64 addr;};

Using this ioctl, a single vcpu register can be set to a specific valuedefined by user space with the passed in struct kvm_one_reg, where idrefers to the register identifier as described below and addr is a pointerto a variable with the respective size. There can be architecture agnosticand architecture specific registers. Each have their own range of operationand their own constants and width. To keep track of the implementedregisters, find a list below:

Arch	Register	Width (bits)
PPC	KVM_REG_PPC_HIOR	64
PPC	KVM_REG_PPC_IAC1	64
PPC	KVM_REG_PPC_IAC2	64
PPC	KVM_REG_PPC_IAC3	64
PPC	KVM_REG_PPC_IAC4	64
PPC	KVM_REG_PPC_DAC1	64
PPC	KVM_REG_PPC_DAC2	64
PPC	KVM_REG_PPC_DABR	64
PPC	KVM_REG_PPC_DSCR	64
PPC	KVM_REG_PPC_PURR	64
PPC	KVM_REG_PPC_SPURR	64
PPC	KVM_REG_PPC_DAR	64
PPC	KVM_REG_PPC_DSISR	32
PPC	KVM_REG_PPC_AMR	64
PPC	KVM_REG_PPC_UAMOR	64
PPC	KVM_REG_PPC_MMCR0	64
PPC	KVM_REG_PPC_MMCR1	64
PPC	KVM_REG_PPC_MMCRA	64
PPC	KVM_REG_PPC_MMCR2	64
PPC	KVM_REG_PPC_MMCRS	64
PPC	KVM_REG_PPC_MMCR3	64
PPC	KVM_REG_PPC_SIAR	64
PPC	KVM_REG_PPC_SDAR	64
PPC	KVM_REG_PPC_SIER	64
PPC	KVM_REG_PPC_SIER2	64
PPC	KVM_REG_PPC_SIER3	64
PPC	KVM_REG_PPC_PMC1	32
PPC	KVM_REG_PPC_PMC2	32
PPC	KVM_REG_PPC_PMC3	32
PPC	KVM_REG_PPC_PMC4	32
PPC	KVM_REG_PPC_PMC5	32
PPC	KVM_REG_PPC_PMC6	32
PPC	KVM_REG_PPC_PMC7	32
PPC	KVM_REG_PPC_PMC8	32
PPC	KVM_REG_PPC_FPR0	64
…
PPC	KVM_REG_PPC_FPR31	64
PPC	KVM_REG_PPC_VR0	128
…
PPC	KVM_REG_PPC_VR31	128
PPC	KVM_REG_PPC_VSR0	128
…
PPC	KVM_REG_PPC_VSR31	128
PPC	KVM_REG_PPC_FPSCR	64
PPC	KVM_REG_PPC_VSCR	32
PPC	KVM_REG_PPC_VPA_ADDR	64
PPC	KVM_REG_PPC_VPA_SLB	128
PPC	KVM_REG_PPC_VPA_DTL	128
PPC	KVM_REG_PPC_EPCR	32
PPC	KVM_REG_PPC_EPR	32
PPC	KVM_REG_PPC_TCR	32
PPC	KVM_REG_PPC_TSR	32
PPC	KVM_REG_PPC_OR_TSR	32
PPC	KVM_REG_PPC_CLEAR_TSR	32
PPC	KVM_REG_PPC_MAS0	32
PPC	KVM_REG_PPC_MAS1	32
PPC	KVM_REG_PPC_MAS2	64
PPC	KVM_REG_PPC_MAS7_3	64
PPC	KVM_REG_PPC_MAS4	32
PPC	KVM_REG_PPC_MAS6	32
PPC	KVM_REG_PPC_MMUCFG	32
PPC	KVM_REG_PPC_TLB0CFG	32
PPC	KVM_REG_PPC_TLB1CFG	32
PPC	KVM_REG_PPC_TLB2CFG	32
PPC	KVM_REG_PPC_TLB3CFG	32
PPC	KVM_REG_PPC_TLB0PS	32
PPC	KVM_REG_PPC_TLB1PS	32
PPC	KVM_REG_PPC_TLB2PS	32
PPC	KVM_REG_PPC_TLB3PS	32
PPC	KVM_REG_PPC_EPTCFG	32
PPC	KVM_REG_PPC_ICP_STATE	64
PPC	KVM_REG_PPC_VP_STATE	128
PPC	KVM_REG_PPC_TB_OFFSET	64
PPC	KVM_REG_PPC_SPMC1	32
PPC	KVM_REG_PPC_SPMC2	32
PPC	KVM_REG_PPC_IAMR	64
PPC	KVM_REG_PPC_TFHAR	64
PPC	KVM_REG_PPC_TFIAR	64
PPC	KVM_REG_PPC_TEXASR	64
PPC	KVM_REG_PPC_FSCR	64
PPC	KVM_REG_PPC_PSPB	32
PPC	KVM_REG_PPC_EBBHR	64
PPC	KVM_REG_PPC_EBBRR	64
PPC	KVM_REG_PPC_BESCR	64
PPC	KVM_REG_PPC_TAR	64
PPC	KVM_REG_PPC_DPDES	64
PPC	KVM_REG_PPC_DAWR	64
PPC	KVM_REG_PPC_DAWRX	64
PPC	KVM_REG_PPC_CIABR	64
PPC	KVM_REG_PPC_IC	64
PPC	KVM_REG_PPC_VTB	64
PPC	KVM_REG_PPC_CSIGR	64
PPC	KVM_REG_PPC_TACR	64
PPC	KVM_REG_PPC_TCSCR	64
PPC	KVM_REG_PPC_PID	64
PPC	KVM_REG_PPC_ACOP	64
PPC	KVM_REG_PPC_VRSAVE	32
PPC	KVM_REG_PPC_LPCR	32
PPC	KVM_REG_PPC_LPCR_64	64
PPC	KVM_REG_PPC_PPR	64
PPC	KVM_REG_PPC_ARCH_COMPAT	32
PPC	KVM_REG_PPC_DABRX	32
PPC	KVM_REG_PPC_WORT	64
PPC	KVM_REG_PPC_SPRG9	64
PPC	KVM_REG_PPC_DBSR	32
PPC	KVM_REG_PPC_TIDR	64
PPC	KVM_REG_PPC_PSSCR	64
PPC	KVM_REG_PPC_DEC_EXPIRY	64
PPC	KVM_REG_PPC_PTCR	64
PPC	KVM_REG_PPC_TM_GPR0	64
…
PPC	KVM_REG_PPC_TM_GPR31	64
PPC	KVM_REG_PPC_TM_VSR0	128
…
PPC	KVM_REG_PPC_TM_VSR63	128
PPC	KVM_REG_PPC_TM_CR	64
PPC	KVM_REG_PPC_TM_LR	64
PPC	KVM_REG_PPC_TM_CTR	64
PPC	KVM_REG_PPC_TM_FPSCR	64
PPC	KVM_REG_PPC_TM_AMR	64
PPC	KVM_REG_PPC_TM_PPR	64
PPC	KVM_REG_PPC_TM_VRSAVE	64
PPC	KVM_REG_PPC_TM_VSCR	32
PPC	KVM_REG_PPC_TM_DSCR	64
PPC	KVM_REG_PPC_TM_TAR	64
PPC	KVM_REG_PPC_TM_XER	64
MIPS	KVM_REG_MIPS_R0	64
…
MIPS	KVM_REG_MIPS_R31	64
MIPS	KVM_REG_MIPS_HI	64
MIPS	KVM_REG_MIPS_LO	64
MIPS	KVM_REG_MIPS_PC	64
MIPS	KVM_REG_MIPS_CP0_INDEX	32
MIPS	KVM_REG_MIPS_CP0_ENTRYLO0	64
MIPS	KVM_REG_MIPS_CP0_ENTRYLO1	64
MIPS	KVM_REG_MIPS_CP0_CONTEXT	64
MIPS	KVM_REG_MIPS_CP0_CONTEXTCONFIG	32
MIPS	KVM_REG_MIPS_CP0_USERLOCAL	64
MIPS	KVM_REG_MIPS_CP0_XCONTEXTCONFIG	64
MIPS	KVM_REG_MIPS_CP0_PAGEMASK	32
MIPS	KVM_REG_MIPS_CP0_PAGEGRAIN	32
MIPS	KVM_REG_MIPS_CP0_SEGCTL0	64
MIPS	KVM_REG_MIPS_CP0_SEGCTL1	64
MIPS	KVM_REG_MIPS_CP0_SEGCTL2	64
MIPS	KVM_REG_MIPS_CP0_PWBASE	64
MIPS	KVM_REG_MIPS_CP0_PWFIELD	64
MIPS	KVM_REG_MIPS_CP0_PWSIZE	64
MIPS	KVM_REG_MIPS_CP0_WIRED	32
MIPS	KVM_REG_MIPS_CP0_PWCTL	32
MIPS	KVM_REG_MIPS_CP0_HWRENA	32
MIPS	KVM_REG_MIPS_CP0_BADVADDR	64
MIPS	KVM_REG_MIPS_CP0_BADINSTR	32
MIPS	KVM_REG_MIPS_CP0_BADINSTRP	32
MIPS	KVM_REG_MIPS_CP0_COUNT	32
MIPS	KVM_REG_MIPS_CP0_ENTRYHI	64
MIPS	KVM_REG_MIPS_CP0_COMPARE	32
MIPS	KVM_REG_MIPS_CP0_STATUS	32
MIPS	KVM_REG_MIPS_CP0_INTCTL	32
MIPS	KVM_REG_MIPS_CP0_CAUSE	32
MIPS	KVM_REG_MIPS_CP0_EPC	64
MIPS	KVM_REG_MIPS_CP0_PRID	32
MIPS	KVM_REG_MIPS_CP0_EBASE	64
MIPS	KVM_REG_MIPS_CP0_CONFIG	32
MIPS	KVM_REG_MIPS_CP0_CONFIG1	32
MIPS	KVM_REG_MIPS_CP0_CONFIG2	32
MIPS	KVM_REG_MIPS_CP0_CONFIG3	32
MIPS	KVM_REG_MIPS_CP0_CONFIG4	32
MIPS	KVM_REG_MIPS_CP0_CONFIG5	32
MIPS	KVM_REG_MIPS_CP0_CONFIG7	32
MIPS	KVM_REG_MIPS_CP0_XCONTEXT	64
MIPS	KVM_REG_MIPS_CP0_ERROREPC	64
MIPS	KVM_REG_MIPS_CP0_KSCRATCH1	64
MIPS	KVM_REG_MIPS_CP0_KSCRATCH2	64
MIPS	KVM_REG_MIPS_CP0_KSCRATCH3	64
MIPS	KVM_REG_MIPS_CP0_KSCRATCH4	64
MIPS	KVM_REG_MIPS_CP0_KSCRATCH5	64
MIPS	KVM_REG_MIPS_CP0_KSCRATCH6	64
MIPS	KVM_REG_MIPS_CP0_MAAR(0..63)	64
MIPS	KVM_REG_MIPS_COUNT_CTL	64
MIPS	KVM_REG_MIPS_COUNT_RESUME	64
MIPS	KVM_REG_MIPS_COUNT_HZ	64
MIPS	KVM_REG_MIPS_FPR_32(0..31)	32
MIPS	KVM_REG_MIPS_FPR_64(0..31)	64
MIPS	KVM_REG_MIPS_VEC_128(0..31)	128
MIPS	KVM_REG_MIPS_FCR_IR	32
MIPS	KVM_REG_MIPS_FCR_CSR	32
MIPS	KVM_REG_MIPS_MSA_IR	32
MIPS	KVM_REG_MIPS_MSA_CSR	32

ARM registers are mapped using the lower 32 bits. The upper 16 of thatis the register group type, or coprocessor number:

ARM core registers have the following id bit patterns:

0x4020 0000 0010 <index into the kvm_regs struct:16>

ARM 32-bit CP15 registers have the following id bit patterns:

0x4020 0000 000F <zero:1> <crn:4> <crm:4> <opc1:4> <opc2:3>

ARM 64-bit CP15 registers have the following id bit patterns:

0x4030 0000 000F <zero:1> <zero:4> <crm:4> <opc1:4> <zero:3>

ARM CCSIDR registers are demultiplexed by CSSELR value:

0x4020 0000 0011 00 <csselr:8>

ARM 32-bit VFP control registers have the following id bit patterns:

0x4020 0000 0012 1 <regno:12>

ARM 64-bit FP registers have the following id bit patterns:

0x4030 0000 0012 0 <regno:12>

ARM firmware pseudo-registers have the following bit pattern:

0x4030 0000 0014 <regno:16>

arm64 registers are mapped using the lower 32 bits. The upper 16 ofthat is the register group type, or coprocessor number:

arm64 core/FP-SIMD registers have the following id bit patterns. Notethat the size of the access is variable, as the kvm_regs structurecontains elements ranging from 32 to 128 bits. The index is a 32bitvalue in the kvm_regs structure seen as a 32bit array:

0x60x0 0000 0010 <index into the kvm_regs struct:16>

Specifically:

arm64 CCSIDR registers are demultiplexed by CSSELR value:

0x6020 0000 0011 00 <csselr:8>

arm64 system registers have the following id bit patterns:

0x6030 0000 0013 <op0:2> <op1:3> <crn:4> <crm:4> <op2:3>

arm64 firmware pseudo-registers have the following bit pattern:

0x6030 0000 0014 <regno:16>

arm64 SVE registers have the following bit patterns:

0x6080 0000 0015 00 <n:5> <slice:5>   Zn bits[2048*slice + 2047 : 2048*slice]0x6050 0000 0015 04 <n:4> <slice:5>   Pn bits[256*slice + 255 : 256*slice]0x6050 0000 0015 060 <slice:5>        FFR bits[256*slice + 255 : 256*slice]0x6060 0000 0015 ffff                 KVM_REG_ARM64_SVE_VLS pseudo-register

Access to register IDs where 2048 * slice >= 128 * max_vq will fail withENOENT. max_vq is the vcpu’s maximum supported vector length in 128-bitquadwords: see[2] below.

These registers are only accessible on vcpus for which SVE is enabled.See KVM_ARM_VCPU_INIT for details.

In addition, except for KVM_REG_ARM64_SVE_VLS, these registers are notaccessible until the vcpu’s SVE configuration has been finalizedusing KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE). See KVM_ARM_VCPU_INITand KVM_ARM_VCPU_FINALIZE for more information about this procedure.

KVM_REG_ARM64_SVE_VLS is a pseudo-register that allows the set of vectorlengths supported by the vcpu to be discovered and configured byuserspace. When transferred to or from user memory via KVM_GET_ONE_REGor KVM_SET_ONE_REG, the value of this register is of type__u64[KVM_ARM64_SVE_VLS_WORDS], and encodes the set of vector lengths asfollows:

__u64 vector_lengths[KVM_ARM64_SVE_VLS_WORDS];if (vq >= SVE_VQ_MIN && vq <= SVE_VQ_MAX &&    ((vector_lengths[(vq - KVM_ARM64_SVE_VQ_MIN) / 64] >>              ((vq - KVM_ARM64_SVE_VQ_MIN) % 64)) & 1))      /* Vector length vq * 16 bytes supported */else      /* Vector length vq * 16 bytes not supported */

(See Documentation/arm64/sve.rst for an explanation of the “vq”nomenclature.)

KVM_REG_ARM64_SVE_VLS is only accessible after KVM_ARM_VCPU_INIT.KVM_ARM_VCPU_INIT initialises it to the best set of vector lengths thatthe host supports.

Userspace may subsequently modify it if desired until the vcpu’s SVEconfiguration is finalized using KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE).

Apart from simply removing all vector lengths from the host set thatexceed some value, support for arbitrarily chosen sets of vector lengthsis hardware-dependent and may not be available. Attempting to configurean invalid set of vector lengths via KVM_SET_ONE_REG will fail withEINVAL.

After the vcpu’s SVE configuration is finalized, further attempts towrite this register will fail with EPERM.

MIPS registers are mapped using the lower 32 bits. The upper 16 of that isthe register group type:

MIPS core registers (see above) have the following id bit patterns:

0x7030 0000 0000 <reg:16>

MIPS CP0 registers (see KVM_REG_MIPS_CP0_* above) have the following id bitpatterns depending on whether they’re 32-bit or 64-bit registers:

0x7020 0000 0001 00 <reg:5> <sel:3>   (32-bit)0x7030 0000 0001 00 <reg:5> <sel:3>   (64-bit)

Note: KVM_REG_MIPS_CP0_ENTRYLO0 and KVM_REG_MIPS_CP0_ENTRYLO1 are the MIPS64versions of the EntryLo registers regardless of the word size of the hosthardware, host kernel, guest, and whether XPA is present in the guest, i.e.with the RI and XI bits (if they exist) in bits 63 and 62 respectively, andthe PFNX field starting at bit 30.

MIPS MAARs (see KVM_REG_MIPS_CP0_MAAR(*) above) have the following id bitpatterns:

0x7030 0000 0001 01 <reg:8>

MIPS KVM control registers (see above) have the following id bit patterns:

0x7030 0000 0002 <reg:16>

MIPS FPU registers (see KVM_REG_MIPS_FPR_{32,64}() above) have the followingid bit patterns depending on the size of the register being accessed. They arealways accessed according to the current guest FPU mode (Status.FR andConfig5.FRE), i.e. as the guest would see them, and they become unpredictableif the guest FPU mode is changed. MIPS SIMD Architecture (MSA) vectorregisters (see KVM_REG_MIPS_VEC_128() above) have similar patterns as theyoverlap the FPU registers:

0x7020 0000 0003 00 <0:3> <reg:5> (32-bit FPU registers)0x7030 0000 0003 00 <0:3> <reg:5> (64-bit FPU registers)0x7040 0000 0003 00 <0:3> <reg:5> (128-bit MSA vector registers)

MIPS FPU control registers (see KVM_REG_MIPS_FCR_{IR,CSR} above) have thefollowing id bit patterns:

0x7020 0000 0003 01 <0:3> <reg:5>

MIPS MSA control registers (see KVM_REG_MIPS_MSA_{IR,CSR} above) have thefollowing id bit patterns:

0x7020 0000 0003 02 <0:3> <reg:5>

4.69 KVM_GET_ONE_REG¶

Errors include:

ENOENT	no such register
EINVAL	invalid register ID, or no such register or used with VMs inprotected virtualization mode on s390
EPERM	(arm64) register access not allowed before vcpu finalization

(These error codes are indicative only: do not rely on a specific errorcode being returned in a specific situation.)

This ioctl allows to receive the value of a single register implementedin a vcpu. The register to read is indicated by the “id” field of thekvm_one_reg struct passed in. On success, the register value can be foundat the memory location pointed to by “addr”.

The list of registers accessible using this interface is identical to thelist in 4.68.

4.70 KVM_KVMCLOCK_CTRL¶

This ioctl sets a flag accessible to the guest indicating that the specifiedvCPU has been paused by the host userspace.

The host will set a flag in the pvclock structure that is checked from thesoft lockup watchdog. The flag is part of the pvclock structure that isshared between guest and host, specifically the second bit of the flagsfield of the pvclock_vcpu_time_info structure. It will be set exclusively bythe host and read/cleared exclusively by the guest. The guest operation ofchecking and clearing the flag must be an atomic operation soload-link/store-conditional, or equivalent must be used. There are two caseswhere the guest will clear the flag: when the soft lockup watchdog timer resetsitself or when a soft lockup is detected. This ioctl can be called any timeafter pausing the vcpu, but before it is resumed.

4.71 KVM_SIGNAL_MSI¶

Directly inject a MSI message. Only valid with in-kernel irqchip that handlesMSI messages.

struct kvm_msi {      __u32 address_lo;      __u32 address_hi;      __u32 data;      __u32 flags;      __u32 devid;      __u8  pad[12];};

flags:

KVM_MSI_VALID_DEVID: devid contains a valid value. The per-VMKVM_CAP_MSI_DEVID capability advertises the requirement to providethe device ID. If this capability is not available, userspaceshould never set the KVM_MSI_VALID_DEVID flag as the ioctl might fail.

If KVM_MSI_VALID_DEVID is set, devid contains a unique device identifierfor the device that wrote the MSI message. For PCI, this is usually aBFD identifier in the lower 16 bits.

On x86, address_hi is ignored unless the KVM_X2APIC_API_USE_32BIT_IDSfeature of KVM_CAP_X2APIC_API capability is enabled. If it is enabled,address_hi bits 31-8 provide bits 31-8 of the destination id. Bits 7-0 ofaddress_hi must be zero.

4.71 KVM_CREATE_PIT2¶

Creates an in-kernel device model for the i8254 PIT. This call is only validafter enabling in-kernel irqchip support via KVM_CREATE_IRQCHIP. The followingparameters have to be passed:

struct kvm_pit_config {      __u32 flags;      __u32 pad[15];};

Valid flags are:

#define KVM_PIT_SPEAKER_DUMMY     1 /* emulate speaker port stub */

PIT timer interrupts may use a per-VM kernel thread for injection. If itexists, this thread will have a name of the following pattern:

kvm-pit/<owner-process-pid>

When running a guest with elevated priorities, the scheduling parameters ofthis thread may have to be adjusted accordingly.

This IOCTL replaces the obsolete KVM_CREATE_PIT.

4.72 KVM_GET_PIT2¶

Retrieves the state of the in-kernel PIT model. Only valid afterKVM_CREATE_PIT2. The state is returned in the following structure:

struct kvm_pit_state2 {      struct kvm_pit_channel_state channels[3];      __u32 flags;      __u32 reserved[9];};

Valid flags are:

/* disable PIT in HPET legacy mode */#define KVM_PIT_FLAGS_HPET_LEGACY  0x00000001

This IOCTL replaces the obsolete KVM_GET_PIT.

4.73 KVM_SET_PIT2¶

Sets the state of the in-kernel PIT model. Only valid after KVM_CREATE_PIT2.See KVM_GET_PIT2 for details on struct kvm_pit_state2.

This IOCTL replaces the obsolete KVM_SET_PIT.

4.74 KVM_PPC_GET_SMMU_INFO¶

This populates and returns a structure describing the features ofthe “Server” class MMU emulation supported by KVM.This can in turn be used by userspace to generate the appropriatedevice-tree properties for the guest operating system.

The structure contains some global information, followed by anarray of supported segment page sizes:

struct kvm_ppc_smmu_info {       __u64 flags;       __u32 slb_size;       __u32 pad;       struct kvm_ppc_one_seg_page_size sps[KVM_PPC_PAGE_SIZES_MAX_SZ];};

The supported flags are:

• KVM_PPC_PAGE_SIZES_REAL:

  When that flag is set, guest page sizes must “fit” the backingstore page sizes. When not set, any page size in the list canbe used regardless of how they are backed by userspace.

• KVM_PPC_1T_SEGMENTS

  The emulated MMU supports 1T segments in addition to thestandard 256M ones.

• KVM_PPC_NO_HASH

  This flag indicates that HPT guests are not supported by KVM,thus all guests must use radix MMU mode.

The “slb_size” field indicates how many SLB entries are supported

The “sps” array contains 8 entries indicating the supported basepage sizes for a segment in increasing order. Each entry is definedas follow:

struct kvm_ppc_one_seg_page_size {     __u32 page_shift;       /* Base page shift of segment (or 0) */     __u32 slb_enc;          /* SLB encoding for BookS */     struct kvm_ppc_one_page_size enc[KVM_PPC_PAGE_SIZES_MAX_SZ];};

An entry with a “page_shift” of 0 is unused. Because the array isorganized in increasing order, a lookup can stop when encouteringsuch an entry.

The “slb_enc” field provides the encoding to use in the SLB for thepage size. The bits are in positions such as the value can directlybe OR’ed into the “vsid” argument of the slbmte instruction.

The “enc” array is a list which for each of those segment base pagesize provides the list of supported actual page sizes (which can beonly larger or equal to the base page size), along with thecorresponding encoding in the hash PTE. Similarly, the array is8 entries sorted by increasing sizes and an entry with a “0” shiftis an empty entry and a terminator:

struct kvm_ppc_one_page_size {     __u32 page_shift;       /* Page shift (or 0) */     __u32 pte_enc;          /* Encoding in the HPTE (>>12) */};

The “pte_enc” field provides a value that can OR’ed into the hashPTE’s RPN field (ie, it needs to be shifted left by 12 to OR itinto the hash PTE second double word).

4.75 KVM_IRQFD¶

Allows setting an eventfd to directly trigger a guest interrupt.kvm_irqfd.fd specifies the file descriptor to use as the eventfd andkvm_irqfd.gsi specifies the irqchip pin toggled by this event. Whenan event is triggered on the eventfd, an interrupt is injected intothe guest using the specified gsi pin. The irqfd is removed usingthe KVM_IRQFD_FLAG_DEASSIGN flag, specifying both kvm_irqfd.fdand kvm_irqfd.gsi.

With KVM_CAP_IRQFD_RESAMPLE, KVM_IRQFD supports a de-assert and notifymechanism allowing emulation of level-triggered, irqfd-basedinterrupts. When KVM_IRQFD_FLAG_RESAMPLE is set the user must pass anadditional eventfd in the kvm_irqfd.resamplefd field. When operatingin resample mode, posting of an interrupt through kvm_irq.fd assertsthe specified gsi in the irqchip. When the irqchip is resampled, suchas from an EOI, the gsi is de-asserted and the user is notified viakvm_irqfd.resamplefd. It is the user’s responsibility to re-queuethe interrupt if the device making use of it still requires service.Note that closing the resamplefd is not sufficient to disable theirqfd. The KVM_IRQFD_FLAG_RESAMPLE is only necessary on assignmentand need not be specified with KVM_IRQFD_FLAG_DEASSIGN.

On arm/arm64, gsi routing being supported, the following can happen:

• in case no routing entry is associated to this gsi, injection fails
• in case the gsi is associated to an irqchip routing entry,irqchip.pin + 32 corresponds to the injected SPI ID.
• in case the gsi is associated to an MSI routing entry, the MSImessage and device ID are translated into an LPI (support restrictedto GICv3 ITS in-kernel emulation).

4.76 KVM_PPC_ALLOCATE_HTAB¶

This requests the host kernel to allocate an MMU hash table for aguest using the PAPR paravirtualization interface. This only doesanything if the kernel is configured to use the Book 3S HV style ofvirtualization. Otherwise the capability doesn’t exist and the ioctlreturns an ENOTTY error. The rest of this description assumes Book 3SHV.

There must be no vcpus running when this ioctl is called; if thereare, it will do nothing and return an EBUSY error.

The parameter is a pointer to a 32-bit unsigned integer variablecontaining the order (log base 2) of the desired size of the hashtable, which must be between 18 and 46. On successful return from theioctl, the value will not be changed by the kernel.

If no hash table has been allocated when any vcpu is asked to run(with the KVM_RUN ioctl), the host kernel will allocate adefault-sized hash table (16 MB).

If this ioctl is called when a hash table has already been allocated,with a different order from the existing hash table, the existing hashtable will be freed and a new one allocated. If this is ioctl iscalled when a hash table has already been allocated of the same orderas specified, the kernel will clear out the existing hash table (zeroall HPTEs). In either case, if the guest is using the virtualizedreal-mode area (VRMA) facility, the kernel will re-create the VMRAHPTEs on the next KVM_RUN of any vcpu.

4.77 KVM_S390_INTERRUPT¶

Allows to inject an interrupt to the guest. Interrupts can be floating(vm ioctl) or per cpu (vcpu ioctl), depending on the interrupt type.

Interrupt parameters are passed via kvm_s390_interrupt:

struct kvm_s390_interrupt {      __u32 type;      __u32 parm;      __u64 parm64;};

type can be one of the following:

KVM_S390_SIGP_STOP (vcpu)

• sigp stop; optional flags in parm

KVM_S390_PROGRAM_INT (vcpu)

• program check; code in parm

KVM_S390_SIGP_SET_PREFIX (vcpu)

• sigp set prefix; prefix address in parm

KVM_S390_RESTART (vcpu)

• restart

KVM_S390_INT_CLOCK_COMP (vcpu)

• clock comparator interrupt

KVM_S390_INT_CPU_TIMER (vcpu)

• CPU timer interrupt

KVM_S390_INT_VIRTIO (vm)

• virtio external interrupt; external interruptparameters in parm and parm64

KVM_S390_INT_SERVICE (vm)

• sclp external interrupt; sclp parameter in parm

KVM_S390_INT_EMERGENCY (vcpu)

• sigp emergency; source cpu in parm

KVM_S390_INT_EXTERNAL_CALL (vcpu)

• sigp external call; source cpu in parm

KVM_S390_INT_IO(ai,cssid,ssid,schid) (vm)

• compound value to indicate anI/O interrupt (ai - adapter interrupt; cssid,ssid,schid - subchannel);I/O interruption parameters in parm (subchannel) and parm64 (intparm,interruption subclass)

KVM_S390_MCHK (vm, vcpu)

• machine check interrupt; cr 14 bits in parm, machine check interruptcode in parm64 (note that machine checks needing further payload are notsupported by this ioctl)

This is an asynchronous vcpu ioctl and can be invoked from any thread.

4.78 KVM_PPC_GET_HTAB_FD¶

This returns a file descriptor that can be used either to read out theentries in the guest’s hashed page table (HPT), or to write entries toinitialize the HPT. The returned fd can only be written to if theKVM_GET_HTAB_WRITE bit is set in the flags field of the argument, andcan only be read if that bit is clear. The argument struct looks likethis:

/* For KVM_PPC_GET_HTAB_FD */struct kvm_get_htab_fd {      __u64   flags;      __u64   start_index;      __u64   reserved[2];};/* Values for kvm_get_htab_fd.flags */#define KVM_GET_HTAB_BOLTED_ONLY      ((__u64)0x1)#define KVM_GET_HTAB_WRITE            ((__u64)0x2)

The ‘start_index’ field gives the index in the HPT of the entry atwhich to start reading. It is ignored when writing.

Reads on the fd will initially supply information about all“interesting” HPT entries. Interesting entries are those with thebolted bit set, if the KVM_GET_HTAB_BOLTED_ONLY bit is set, otherwiseall entries. When the end of the HPT is reached, the read() willreturn. If read() is called again on the fd, it will start again fromthe beginning of the HPT, but will only return HPT entries that havechanged since they were last read.

Data read or written is structured as a header (8 bytes) followed by aseries of valid HPT entries (16 bytes) each. The header indicates howmany valid HPT entries there are and how many invalid entries followthe valid entries. The invalid entries are not represented explicitlyin the stream. The header format is:

struct kvm_get_htab_header {      __u32   index;      __u16   n_valid;      __u16   n_invalid;};

Writes to the fd create HPT entries starting at the index given in theheader; first ‘n_valid’ valid entries with contents from the datawritten, then ‘n_invalid’ invalid entries, invalidating any previouslyvalid entries found.

4.79 KVM_CREATE_DEVICE¶

Errors:

ENODEV	The device type is unknown or unsupported
EEXIST	Device already created, and this type of device may notbe instantiated multiple times

Other error conditions may be defined by individual device types orhave their standard meanings.

Creates an emulated device in the kernel. The file descriptor returnedin fd can be used with KVM_SET/GET/HAS_DEVICE_ATTR.

If the KVM_CREATE_DEVICE_TEST flag is set, only test whether thedevice type is supported (not necessarily whether it can be createdin the current vm).

Individual devices should not define flags. Attributes should be usedfor specifying any behavior that is not implied by the device typenumber.

struct kvm_create_device {      __u32   type;   /* in: KVM_DEV_TYPE_xxx */      __u32   fd;     /* out: device handle */      __u32   flags;  /* in: KVM_CREATE_DEVICE_xxx */};

4.80 KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR¶

Errors:

ENXIO	The group or attribute is unknown/unsupported for this deviceor hardware support is missing.
EPERM	The attribute cannot (currently) be accessed this way(e.g. read-only attribute, or attribute that only makessense when the device is in a different state)

Other error conditions may be defined by individual device types.

Gets/sets a specified piece of device configuration and/or state. Thesemantics are device-specific. See individual device documentation inthe “devices” directory. As with ONE_REG, the size of the datatransferred is defined by the particular attribute.

struct kvm_device_attr {      __u32   flags;          /* no flags currently defined */      __u32   group;          /* device-defined */      __u64   attr;           /* group-defined */      __u64   addr;           /* userspace address of attr data */};

4.81 KVM_HAS_DEVICE_ATTR¶

Errors:

ENXIO

The group or attribute is unknown/unsupported for this deviceor hardware support is missing.

Tests whether a device supports a particular attribute. A successfulreturn indicates the attribute is implemented. It does not necessarilyindicate that the attribute can be read or written in the device’scurrent state. “addr” is ignored.

4.82 KVM_ARM_VCPU_INIT¶

Errors:

EINVAL	the target is unknown, or the combination of features is invalid.
ENOENT	a features bit specified is unknown.

This tells KVM what type of CPU to present to the guest, and whatoptional features it should have.  This will cause a reset of the cpuregisters to their initial values.  If this is not called, KVM_RUN willreturn ENOEXEC for that vcpu.

Note that because some registers reflect machine topology, all vcpusshould be created before this ioctl is invoked.

Userspace can call this function multiple times for a given vcpu, includingafter the vcpu has been run. This will reset the vcpu to its initialstate. All calls to this function after the initial call must use the sametarget and same set of feature flags, otherwise EINVAL will be returned.

Possible features:

• KVM_ARM_VCPU_POWER_OFF: Starts the CPU in a power-off state.Depends on KVM_CAP_ARM_PSCI. If not set, the CPU will be powered onand execute guest code when KVM_RUN is called.

• KVM_ARM_VCPU_EL1_32BIT: Starts the CPU in a 32bit mode.Depends on KVM_CAP_ARM_EL1_32BIT (arm64 only).

• KVM_ARM_VCPU_PSCI_0_2: Emulate PSCI v0.2 (or a future revisionbackward compatible with v0.2) for the CPU.Depends on KVM_CAP_ARM_PSCI_0_2.

• KVM_ARM_VCPU_PMU_V3: Emulate PMUv3 for the CPU.Depends on KVM_CAP_ARM_PMU_V3.

• KVM_ARM_VCPU_PTRAUTH_ADDRESS: Enables Address Pointer authenticationfor arm64 only.Depends on KVM_CAP_ARM_PTRAUTH_ADDRESS.If KVM_CAP_ARM_PTRAUTH_ADDRESS and KVM_CAP_ARM_PTRAUTH_GENERIC areboth present, then both KVM_ARM_VCPU_PTRAUTH_ADDRESS andKVM_ARM_VCPU_PTRAUTH_GENERIC must be requested or neither must berequested.

• KVM_ARM_VCPU_PTRAUTH_GENERIC: Enables Generic Pointer authenticationfor arm64 only.Depends on KVM_CAP_ARM_PTRAUTH_GENERIC.If KVM_CAP_ARM_PTRAUTH_ADDRESS and KVM_CAP_ARM_PTRAUTH_GENERIC areboth present, then both KVM_ARM_VCPU_PTRAUTH_ADDRESS andKVM_ARM_VCPU_PTRAUTH_GENERIC must be requested or neither must berequested.

• KVM_ARM_VCPU_SVE: Enables SVE for the CPU (arm64 only).Depends on KVM_CAP_ARM_SVE.Requires KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE):

  • After KVM_ARM_VCPU_INIT:

    • KVM_REG_ARM64_SVE_VLS may be read using KVM_GET_ONE_REG: theinitial value of this pseudo-register indicates the best set ofvector lengths possible for a vcpu on this host.

  • Before KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE):

    • KVM_RUN and KVM_GET_REG_LIST are not available;
    • KVM_GET_ONE_REG and KVM_SET_ONE_REG cannot be used to accessthe scalable archietctural SVE registersKVM_REG_ARM64_SVE_ZREG(), KVM_REG_ARM64_SVE_PREG() orKVM_REG_ARM64_SVE_FFR;
    • KVM_REG_ARM64_SVE_VLS may optionally be written usingKVM_SET_ONE_REG, to modify the set of vector lengths availablefor the vcpu.

  • After KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE):

    • the KVM_REG_ARM64_SVE_VLS pseudo-register is immutable, and canno longer be written using KVM_SET_ONE_REG.

4.83 KVM_ARM_PREFERRED_TARGET¶

Errors:

ENODEV

no preferred target available for the host

This queries KVM for preferred CPU target type which can be emulatedby KVM on underlying host.

The ioctl returns struct kvm_vcpu_init instance containing informationabout preferred CPU target type and recommended features for it. Thekvm_vcpu_init->features bitmap returned will have feature bits set ifthe preferred target recommends setting these features, but this isnot mandatory.

The information returned by this ioctl can be used to prepare an instanceof struct kvm_vcpu_init for KVM_ARM_VCPU_INIT ioctl which will result inVCPU matching underlying host.

4.84 KVM_GET_REG_LIST¶

Errors:

E2BIG

the reg index list is too big to fit in the array specified bythe user (the number required will be written into n).

struct kvm_reg_list {      __u64 n; /* number of registers in reg[] */      __u64 reg[0];};

This ioctl returns the guest registers that are supported for theKVM_GET_ONE_REG/KVM_SET_ONE_REG calls.

4.85 KVM_ARM_SET_DEVICE_ADDR (deprecated)¶

Errors:

ENODEV	The device id is unknown
ENXIO	Device not supported on current system
EEXIST	Address already set
E2BIG	Address outside guest physical address space
EBUSY	Address overlaps with other device range

struct kvm_arm_device_addr {      __u64 id;      __u64 addr;};

Specify a device address in the guest’s physical address space where guestscan access emulated or directly exposed devices, which the host kernel needsto know about. The id field is an architecture specific identifier for aspecific device.

ARM/arm64 divides the id field into two parts, a device id and anaddress type id specific to the individual device:

bits:  | 63        ...       32 | 31    ...    16 | 15    ...    0 |field: |        0x00000000      |     device id   |  addr type id  |

ARM/arm64 currently only require this when using the in-kernel GICsupport for the hardware VGIC features, using KVM_ARM_DEVICE_VGIC_V2as the device id. When setting the base address for the guest’smapping of the VGIC virtual CPU and distributor interface, the ioctlmust be called after calling KVM_CREATE_IRQCHIP, but before callingKVM_RUN on any of the VCPUs. Calling this ioctl twice for any of thebase addresses will return -EEXIST.

Note, this IOCTL is deprecated and the more flexible SET/GET_DEVICE_ATTR APIshould be used instead.

4.86 KVM_PPC_RTAS_DEFINE_TOKEN¶

Defines a token value for a RTAS (Run Time Abstraction Services)service in order to allow it to be handled in the kernel. Theargument struct gives the name of the service, which must be the nameof a service that has a kernel-side implementation. If the tokenvalue is non-zero, it will be associated with that service, andsubsequent RTAS calls by the guest specifying that token will behandled by the kernel. If the token value is 0, then any tokenassociated with the service will be forgotten, and subsequent RTAScalls by the guest for that service will be passed to userspace to behandled.

4.87 KVM_SET_GUEST_DEBUG¶

struct kvm_guest_debug {     __u32 control;     __u32 pad;     struct kvm_guest_debug_arch arch;};

Set up the processor specific debug registers and configure vcpu forhandling guest debug events. There are two parts to the structure, thefirst a control bitfield indicates the type of debug events to handlewhen running. Common control bits are:

• KVM_GUESTDBG_ENABLE: guest debugging is enabled
• KVM_GUESTDBG_SINGLESTEP: the next run should single-step

The top 16 bits of the control field are architecture specific controlflags which can include the following:

• KVM_GUESTDBG_USE_SW_BP: using software breakpoints [x86, arm64]
• KVM_GUESTDBG_USE_HW_BP: using hardware breakpoints [x86, s390, arm64]
• KVM_GUESTDBG_INJECT_DB: inject DB type exception [x86]
• KVM_GUESTDBG_INJECT_BP: inject BP type exception [x86]
• KVM_GUESTDBG_EXIT_PENDING: trigger an immediate guest exit [s390]

For example KVM_GUESTDBG_USE_SW_BP indicates that software breakpointsare enabled in memory so we need to ensure breakpoint exceptions arecorrectly trapped and the KVM run loop exits at the breakpoint and notrunning off into the normal guest vector. For KVM_GUESTDBG_USE_HW_BPwe need to ensure the guest vCPUs architecture specific registers areupdated to the correct (supplied) values.

The second part of the structure is architecture specific andtypically contains a set of debug registers.

For arm64 the number of debug registers is implementation defined andcan be determined by querying the KVM_CAP_GUEST_DEBUG_HW_BPS andKVM_CAP_GUEST_DEBUG_HW_WPS capabilities which return a positive numberindicating the number of supported registers.

For ppc, the KVM_CAP_PPC_GUEST_DEBUG_SSTEP capability indicates whetherthe single-step debug event (KVM_GUESTDBG_SINGLESTEP) is supported.

When debug events exit the main run loop with the reasonKVM_EXIT_DEBUG with the kvm_debug_exit_arch part of the kvm_runstructure containing architecture specific debug information.

4.88 KVM_GET_EMULATED_CPUID¶

struct kvm_cpuid2 {      __u32 nent;      __u32 flags;      struct kvm_cpuid_entry2 entries[0];};

The member ‘flags’ is used for passing flags from userspace.

#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX               BIT(0)#define KVM_CPUID_FLAG_STATEFUL_FUNC          BIT(1) /* deprecated */#define KVM_CPUID_FLAG_STATE_READ_NEXT                BIT(2) /* deprecated */struct kvm_cpuid_entry2 {      __u32 function;      __u32 index;      __u32 flags;      __u32 eax;      __u32 ebx;      __u32 ecx;      __u32 edx;      __u32 padding[3];};

This ioctl returns x86 cpuid features which are emulated bykvm.Userspace can use the information returned by this ioctl to querywhich features are emulated by kvm instead of being present natively.

Userspace invokes KVM_GET_EMULATED_CPUID by passing a kvm_cpuid2structure with the ‘nent’ field indicating the number of entries inthe variable-size array ‘entries’. If the number of entries is too lowto describe the cpu capabilities, an error (E2BIG) is returned. If thenumber is too high, the ‘nent’ field is adjusted and an error (ENOMEM)is returned. If the number is just right, the ‘nent’ field is adjustedto the number of valid entries in the ‘entries’ array, which is thenfilled.

The entries returned are the set CPUID bits of the respective featureswhich kvm emulates, as returned by the CPUID instruction, with unknownor unsupported feature bits cleared.

Features like x2apic, for example, may not be present in the host cpubut are exposed by kvm in KVM_GET_SUPPORTED_CPUID because they can beemulated efficiently and thus not included here.

The fields in each entry are defined as follows:

function:

the eax value used to obtain the entry

index:

the ecx value used to obtain the entry (for entries that areaffected by ecx)

flags:

an OR of zero or more of the following:

KVM_CPUID_FLAG_SIGNIFCANT_INDEX:

if the index field is valid

eax, ebx, ecx, edx:

the values returned by the cpuid instruction forthis function/index combination

4.89 KVM_S390_MEM_OP¶

Read or write data from/to the logical (virtual) memory of a VCPU.

Parameters are specified via the following structure:

struct kvm_s390_mem_op {      __u64 gaddr;            /* the guest address */      __u64 flags;            /* flags */      __u32 size;             /* amount of bytes */      __u32 op;               /* type of operation */      __u64 buf;              /* buffer in userspace */      __u8 ar;                /* the access register number */      __u8 reserved[31];      /* should be set to 0 */};

The type of operation is specified in the “op” field. It is eitherKVM_S390_MEMOP_LOGICAL_READ for reading from logical memory space orKVM_S390_MEMOP_LOGICAL_WRITE for writing to logical memory space. TheKVM_S390_MEMOP_F_CHECK_ONLY flag can be set in the “flags” field to checkwhether the corresponding memory access would create an access exception(without touching the data in the memory at the destination). In case anaccess exception occurred while walking the MMU tables of the guest, theioctl returns a positive error number to indicate the type of exception.This exception is also raised directly at the corresponding VCPU if theflag KVM_S390_MEMOP_F_INJECT_EXCEPTION is set in the “flags” field.

The start address of the memory region has to be specified in the “gaddr”field, and the length of the region in the “size” field (which must notbe 0). The maximum value for “size” can be obtained by checking theKVM_CAP_S390_MEM_OP capability. “buf” is the buffer supplied by theuserspace application where the read data should be written to forKVM_S390_MEMOP_LOGICAL_READ, or where the data that should be written isstored for a KVM_S390_MEMOP_LOGICAL_WRITE. When KVM_S390_MEMOP_F_CHECK_ONLYis specified, “buf” is unused and can be NULL. “ar” designates the accessregister number to be used; the valid range is 0..15.

The “reserved” field is meant for future extensions. It is not used byKVM with the currently defined set of flags.

4.90 KVM_S390_GET_SKEYS¶

This ioctl is used to get guest storage key values on the s390architecture. The ioctl takes parameters via the kvm_s390_skeys struct:

struct kvm_s390_skeys {      __u64 start_gfn;      __u64 count;      __u64 skeydata_addr;      __u32 flags;      __u32 reserved[9];};

The start_gfn field is the number of the first guest frame whose storage keysyou want to get.

The count field is the number of consecutive frames (starting from start_gfn)whose storage keys to get. The count field must be at least 1 and the maximumallowed value is defined as KVM_S390_SKEYS_ALLOC_MAX. Values outside this rangewill cause the ioctl to return -EINVAL.

The skeydata_addr field is the address to a buffer large enough to hold countbytes. This buffer will be filled with storage key data by the ioctl.

4.91 KVM_S390_SET_SKEYS¶

This ioctl is used to set guest storage key values on the s390architecture. The ioctl takes parameters via the kvm_s390_skeys struct.See section on KVM_S390_GET_SKEYS for struct definition.

The start_gfn field is the number of the first guest frame whose storage keysyou want to set.

The count field is the number of consecutive frames (starting from start_gfn)whose storage keys to get. The count field must be at least 1 and the maximumallowed value is defined as KVM_S390_SKEYS_ALLOC_MAX. Values outside this rangewill cause the ioctl to return -EINVAL.

The skeydata_addr field is the address to a buffer containing count bytes ofstorage keys. Each byte in the buffer will be set as the storage key for asingle frame starting at start_gfn for count frames.

Note: If any architecturally invalid key value is found in the given data thenthe ioctl will return -EINVAL.

4.92 KVM_S390_IRQ¶

Errors:

EINVAL	interrupt type is invalidtype is KVM_S390_SIGP_STOP and flag parameter is invalid value,type is KVM_S390_INT_EXTERNAL_CALL and code is biggerthan the maximum of VCPUs
EBUSY	type is KVM_S390_SIGP_SET_PREFIX and vcpu is not stopped,type is KVM_S390_SIGP_STOP and a stop irq is already pending,type is KVM_S390_INT_EXTERNAL_CALL and an external call interruptis already pending

Allows to inject an interrupt to the guest.

Using struct kvm_s390_irq as a parameter allowsto inject additional payload which is notpossible via KVM_S390_INTERRUPT.

Interrupt parameters are passed via kvm_s390_irq:

struct kvm_s390_irq {      __u64 type;      union {              struct kvm_s390_io_info io;              struct kvm_s390_ext_info ext;              struct kvm_s390_pgm_info pgm;              struct kvm_s390_emerg_info emerg;              struct kvm_s390_extcall_info extcall;              struct kvm_s390_prefix_info prefix;              struct kvm_s390_stop_info stop;              struct kvm_s390_mchk_info mchk;              char reserved[64];      } u;};

type can be one of the following:

• KVM_S390_SIGP_STOP - sigp stop; parameter in .stop
• KVM_S390_PROGRAM_INT - program check; parameters in .pgm
• KVM_S390_SIGP_SET_PREFIX - sigp set prefix; parameters in .prefix
• KVM_S390_RESTART - restart; no parameters
• KVM_S390_INT_CLOCK_COMP - clock comparator interrupt; no parameters
• KVM_S390_INT_CPU_TIMER - CPU timer interrupt; no parameters
• KVM_S390_INT_EMERGENCY - sigp emergency; parameters in .emerg
• KVM_S390_INT_EXTERNAL_CALL - sigp external call; parameters in .extcall
• KVM_S390_MCHK - machine check interrupt; parameters in .mchk

This is an asynchronous vcpu ioctl and can be invoked from any thread.

4.94 KVM_S390_GET_IRQ_STATE¶

This ioctl allows userspace to retrieve the complete state of all currentlypending interrupts in a single buffer. Use cases include migrationand introspection. The parameter structure contains the address of auserspace buffer and its length:

struct kvm_s390_irq_state {      __u64 buf;      __u32 flags;        /* will stay unused for compatibility reasons */      __u32 len;      __u32 reserved[4];  /* will stay unused for compatibility reasons */};

Userspace passes in the above struct and for each pending interrupt astruct kvm_s390_irq is copied to the provided buffer.

The structure contains a flags and a reserved field for future extensions. Asthe kernel never checked for flags == 0 and QEMU never pre-zeroed flags andreserved, these fields can not be used in the future without breakingcompatibility.

If -ENOBUFS is returned the buffer provided was too small and userspacemay retry with a bigger buffer.

4.95 KVM_S390_SET_IRQ_STATE¶

This ioctl allows userspace to set the complete state of all cpu-localinterrupts currently pending for the vcpu. It is intended for restoringinterrupt state after a migration. The input parameter is a userspace buffercontaining a struct kvm_s390_irq_state:

struct kvm_s390_irq_state {      __u64 buf;      __u32 flags;        /* will stay unused for compatibility reasons */      __u32 len;      __u32 reserved[4];  /* will stay unused for compatibility reasons */};

The restrictions for flags and reserved apply as well.(see KVM_S390_GET_IRQ_STATE)

The userspace memory referenced by buf contains a struct kvm_s390_irqfor each interrupt to be injected into the guest.If one of the interrupts could not be injected for some reason theioctl aborts.

len must be a multiple of sizeof(struct kvm_s390_irq). It must be > 0and it must not exceed (max_vcpus + 32) * sizeof(struct kvm_s390_irq),which is the maximum number of possibly pending cpu-local interrupts.

4.96 KVM_SMI¶

Queues an SMI on the thread’s vcpu.

4.97 KVM_CAP_PPC_MULTITCE¶

This capability means the kernel is capable of handling hypercallsH_PUT_TCE_INDIRECT and H_STUFF_TCE without passing those into the userspace. This significantly accelerates DMA operations for PPC KVM guests.User space should expect that its handlers for these hypercallsare not going to be called if user space previously registered LIOBNin KVM (via KVM_CREATE_SPAPR_TCE or similar calls).

In order to enable H_PUT_TCE_INDIRECT and H_STUFF_TCE use in the guest,user space might have to advertise it for the guest. For example,IBM pSeries (sPAPR) guest starts using them if “hcall-multi-tce” ispresent in the “ibm,hypertas-functions” device-tree property.

The hypercalls mentioned above may or may not be processed successfullyin the kernel based fast path. If they can not be handled by the kernel,they will get passed on to user space. So user space still has to havean implementation for these despite the in kernel acceleration.

This capability is always enabled.

4.98 KVM_CREATE_SPAPR_TCE_64¶

This is an extension for KVM_CAP_SPAPR_TCE which only supports 32bitwindows, described in 4.62 KVM_CREATE_SPAPR_TCE

This capability uses extended struct in ioctl interface:

/* for KVM_CAP_SPAPR_TCE_64 */struct kvm_create_spapr_tce_64 {      __u64 liobn;      __u32 page_shift;      __u32 flags;      __u64 offset;   /* in pages */      __u64 size;     /* in pages */};

The aim of extension is to support an additional bigger DMA window witha variable page size.KVM_CREATE_SPAPR_TCE_64 receives a 64bit window size, an IOMMU page shift anda bus offset of the corresponding DMA window, @size and @offset are numbersof IOMMU pages.

@flags are not used at the moment.

The rest of functionality is identical to KVM_CREATE_SPAPR_TCE.

4.99 KVM_REINJECT_CONTROL¶

i8254 (PIT) has two modes, reinject and !reinject. The default is reinject,where KVM queues elapsed i8254 ticks and monitors completion of interrupt fromvector(s) that i8254 injects. Reinject mode dequeues a tick and injects itsinterrupt whenever there isn’t a pending interrupt from i8254.!reinject mode injects an interrupt as soon as a tick arrives.

struct kvm_reinject_control {      __u8 pit_reinject;      __u8 reserved[31];};

pit_reinject = 0 (!reinject mode) is recommended, unless running an oldoperating system that uses the PIT for timing (e.g. Linux 2.4.x).

4.100 KVM_PPC_CONFIGURE_V3_MMU¶

This ioctl controls whether the guest will use radix or HPT (hashedpage table) translation, and sets the pointer to the process table forthe guest.

struct kvm_ppc_mmuv3_cfg {      __u64   flags;      __u64   process_table;};

There are two bits that can be set in flags; KVM_PPC_MMUV3_RADIX andKVM_PPC_MMUV3_GTSE. KVM_PPC_MMUV3_RADIX, if set, configures the guestto use radix tree translation, and if clear, to use HPT translation.KVM_PPC_MMUV3_GTSE, if set and if KVM permits it, configures the guestto be able to use the global TLB and SLB invalidation instructions;if clear, the guest may not use these instructions.

The process_table field specifies the address and size of the guestprocess table, which is in the guest’s space. This field is formattedas the second doubleword of the partition table entry, as defined inthe Power ISA V3.00, Book III section 5.7.6.1.

4.101 KVM_PPC_GET_RMMU_INFO¶

This ioctl returns a structure containing two things: (a) a listcontaining supported radix tree geometries, and (b) a list that mapspage sizes to put in the “AP” (actual page size) field for the tlbie(TLB invalidate entry) instruction.

struct kvm_ppc_rmmu_info {      struct kvm_ppc_radix_geom {              __u8    page_shift;              __u8    level_bits[4];              __u8    pad[3];      }       geometries[8];      __u32   ap_encodings[8];};

The geometries[] field gives up to 8 supported geometries for theradix page table, in terms of the log base 2 of the smallest pagesize, and the number of bits indexed at each level of the tree, fromthe PTE level up to the PGD level in that order. Any unused entrieswill have 0 in the page_shift field.

The ap_encodings gives the supported page sizes and their AP fieldencodings, encoded with the AP value in the top 3 bits and the logbase 2 of the page size in the bottom 6 bits.

4.102 KVM_PPC_RESIZE_HPT_PREPARE¶

struct kvm_ppc_rmmu_info {      struct kvm_ppc_radix_geom {              __u8    page_shift;              __u8    level_bits[4];              __u8    pad[3];      }       geometries[8];      __u32   ap_encodings[8];};

The geometries[] field gives up to 8 supported geometries for theradix page table, in terms of the log base 2 of the smallest pagesize, and the number of bits indexed at each level of the tree, fromthe PTE level up to the PGD level in that order. Any unused entrieswill have 0 in the page_shift field.

The ap_encodings gives the supported page sizes and their AP fieldencodings, encoded with the AP value in the top 3 bits and the logbase 2 of the page size in the bottom 6 bits.

4.102 KVM_PPC_RESIZE_HPT_PREPARE¶

Used to implement the PAPR extension for runtime resizing of a guest’sHashed Page Table (HPT). Specifically this starts, stops or monitorsthe preparation of a new potential HPT for the guest, essentiallyimplementing the H_RESIZE_HPT_PREPARE hypercall.

If called with shift > 0 when there is no pending HPT for the guest,this begins preparation of a new pending HPT of size 2^(shift) bytes.It then returns a positive integer with the estimated number ofmilliseconds until preparation is complete.

If called when there is a pending HPT whose size does not match thatrequested in the parameters, discards the existing pending HPT andcreates a new one as above.

If called when there is a pending HPT of the size requested, will:

• If preparation of the pending HPT is already complete, return 0
• If preparation of the pending HPT has failed, return an errorcode, then discard the pending HPT.
• If preparation of the pending HPT is still in progress, return anestimated number of milliseconds until preparation is complete.

If called with shift == 0, discards any currently pending HPT andreturns 0 (i.e. cancels any in-progress preparation).

flags is reserved for future expansion, currently setting any bits inflags will result in an -EINVAL.

Normally this will be called repeatedly with the same parameters untilit returns <= 0. The first call will initiate preparation, subsequentones will monitor preparation until it completes or fails.

struct kvm_ppc_resize_hpt {      __u64 flags;      __u32 shift;      __u32 pad;};

4.103 KVM_PPC_RESIZE_HPT_COMMIT¶

Used to implement the PAPR extension for runtime resizing of a guest’sHashed Page Table (HPT). Specifically this requests that the guest betransferred to working with the new HPT, essentially implementing theH_RESIZE_HPT_COMMIT hypercall.

This should only be called after KVM_PPC_RESIZE_HPT_PREPARE hasreturned 0 with the same parameters. In other casesKVM_PPC_RESIZE_HPT_COMMIT will return an error (usually -ENXIO or-EBUSY, though others may be possible if the preparation was started,but failed).

This will have undefined effects on the guest if it has not alreadyplaced itself in a quiescent state where no vcpu will make MMU enabledmemory accesses.

On succsful completion, the pending HPT will become the guest’s activeHPT and the previous HPT will be discarded.

On failure, the guest will still be operating on its previous HPT.

struct kvm_ppc_resize_hpt {      __u64 flags;      __u32 shift;      __u32 pad;};

4.104 KVM_X86_GET_MCE_CAP_SUPPORTED¶

Returns supported MCE capabilities. The u64 mce_cap parameterhas the same format as the MSR_IA32_MCG_CAP register. Supportedcapabilities will have the corresponding bits set.

4.105 KVM_X86_SETUP_MCE¶

Initializes MCE support for use. The u64 mcg_cap parameterhas the same format as the MSR_IA32_MCG_CAP register andspecifies which capabilities should be enabled. The maximumsupported number of error-reporting banks can be retrieved whenchecking for KVM_CAP_MCE. The supported capabilities can beretrieved with KVM_X86_GET_MCE_CAP_SUPPORTED.

4.106 KVM_X86_SET_MCE¶

Inject a machine check error (MCE) into the guest. The inputparameter is:

struct kvm_x86_mce {      __u64 status;      __u64 addr;      __u64 misc;      __u64 mcg_status;      __u8 bank;      __u8 pad1[7];      __u64 pad2[3];};

If the MCE being reported is an uncorrected error, KVM willinject it as an MCE exception into the guest. If the guestMCG_STATUS register reports that an MCE is in progress, KVMcauses an KVM_EXIT_SHUTDOWN vmexit.

Otherwise, if the MCE is a corrected error, KVM will juststore it in the corresponding bank (provided this bank isnot holding a previously reported uncorrected error).

4.107 KVM_S390_GET_CMMA_BITS¶

This ioctl is used to get the values of the CMMA bits on the s390architecture. It is meant to be used in two scenarios:

• During live migration to save the CMMA values. Live migration needsto be enabled via the KVM_REQ_START_MIGRATION VM property.
• To non-destructively peek at the CMMA values, with the flagKVM_S390_CMMA_PEEK set.

The ioctl takes parameters via the kvm_s390_cmma_log struct. The desiredvalues are written to a buffer whose location is indicated via the “values”member in the kvm_s390_cmma_log struct. The values in the input struct arealso updated as needed.

Each CMMA value takes up one byte.

struct kvm_s390_cmma_log {      __u64 start_gfn;      __u32 count;      __u32 flags;      union {              __u64 remaining;              __u64 mask;      };      __u64 values;};

start_gfn is the number of the first guest frame whose CMMA values areto be retrieved,

count is the length of the buffer in bytes,

values points to the buffer where the result will be written to.

If count is greater than KVM_S390_SKEYS_MAX, then it is considered to beKVM_S390_SKEYS_MAX. KVM_S390_SKEYS_MAX is re-used for consistency withother ioctls.

The result is written in the buffer pointed to by the field values, andthe values of the input parameter are updated as follows.

Depending on the flags, different actions are performed. The onlysupported flag so far is KVM_S390_CMMA_PEEK.

The default behaviour if KVM_S390_CMMA_PEEK is not set is:start_gfn will indicate the first page frame whose CMMA bits were dirty.It is not necessarily the same as the one passed as input, as clean pagesare skipped.

count will indicate the number of bytes actually written in the buffer.It can (and very often will) be smaller than the input value, since thebuffer is only filled until 16 bytes of clean values are found (whichare then not copied in the buffer). Since a CMMA migration block needsthe base address and the length, for a total of 16 bytes, we will sendback some clean data if there is some dirty data afterwards, as long asthe size of the clean data does not exceed the size of the header. Thisallows to minimize the amount of data to be saved or transferred overthe network at the expense of more roundtrips to userspace. The nextinvocation of the ioctl will skip over all the clean values, savingpotentially more than just the 16 bytes we found.

If KVM_S390_CMMA_PEEK is set:the existing storage attributes are read even when not in migrationmode, and no other action is performed;

the output start_gfn will be equal to the input start_gfn,

the output count will be equal to the input count, except if the end ofmemory has been reached.

In both cases:the field “remaining” will indicate the total number of dirty CMMA valuesstill remaining, or 0 if KVM_S390_CMMA_PEEK is set and migration mode isnot enabled.

mask is unused.

values points to the userspace buffer where the result will be stored.

This ioctl can fail with -ENOMEM if not enough memory can be allocated tocomplete the task, with -ENXIO if CMMA is not enabled, with -EINVAL ifKVM_S390_CMMA_PEEK is not set but migration mode was not enabled, with-EFAULT if the userspace address is invalid or if no page table ispresent for the addresses (e.g. when using hugepages).

4.108 KVM_S390_SET_CMMA_BITS¶

This ioctl is used to set the values of the CMMA bits on the s390architecture. It is meant to be used during live migration to restorethe CMMA values, but there are no restrictions on its use.The ioctl takes parameters via the kvm_s390_cmma_values struct.Each CMMA value takes up one byte.

struct kvm_s390_cmma_log {      __u64 start_gfn;      __u32 count;      __u32 flags;      union {              __u64 remaining;              __u64 mask;      };      __u64 values;};

start_gfn indicates the starting guest frame number,

count indicates how many values are to be considered in the buffer,

flags is not used and must be 0.

mask indicates which PGSTE bits are to be considered.

remaining is not used.

values points to the buffer in userspace where to store the values.

This ioctl can fail with -ENOMEM if not enough memory can be allocated tocomplete the task, with -ENXIO if CMMA is not enabled, with -EINVAL ifthe count field is too large (e.g. more than KVM_S390_CMMA_SIZE_MAX) orif the flags field was not 0, with -EFAULT if the userspace address isinvalid, if invalid pages are written to (e.g. after the end of memory)or if no page table is present for the addresses (e.g. when usinghugepages).

4.109 KVM_PPC_GET_CPU_CHAR¶

This ioctl gives userspace information about certain characteristicsof the CPU relating to speculative execution of instructions andpossible information leakage resulting from speculative execution (seeCVE-2017-5715, CVE-2017-5753 and CVE-2017-5754). The information isreturned in struct kvm_ppc_cpu_char, which looks like this:

struct kvm_ppc_cpu_char {      __u64   character;              /* characteristics of the CPU */      __u64   behaviour;              /* recommended software behaviour */      __u64   character_mask;         /* valid bits in character */      __u64   behaviour_mask;         /* valid bits in behaviour */};

For extensibility, the character_mask and behaviour_mask fieldsindicate which bits of character and behaviour have been filled in bythe kernel. If the set of defined bits is extended in future thenuserspace will be able to tell whether it is running on a kernel thatknows about the new bits.

The character field describes attributes of the CPU which can helpwith preventing inadvertent information disclosure - specifically,whether there is an instruction to flash-invalidate the L1 data cache(ori 30,30,0 or mtspr SPRN_TRIG2,rN), whether the L1 data cache is setto a mode where entries can only be used by the thread that createdthem, whether the bcctr[l] instruction prevents speculation, andwhether a speculation barrier instruction (ori 31,31,0) is provided.

The behaviour field describes actions that software should take toprevent inadvertent information disclosure, and thus describes whichvulnerabilities the hardware is subject to; specifically whether theL1 data cache should be flushed when returning to user mode from thekernel, and whether a speculation barrier should be placed between anarray bounds check and the array access.

These fields use the same bit definitions as the newH_GET_CPU_CHARACTERISTICS hypercall.

4.110 KVM_MEMORY_ENCRYPT_OP¶

If the platform supports creating encrypted VMs then this ioctl can be usedfor issuing platform-specific memory encryption commands to manage thoseencrypted VMs.

Currently, this ioctl is used for issuing Secure Encrypted Virtualization(SEV) commands on AMD Processors. The SEV commands are defined inDocumentation/virt/kvm/amd-memory-encryption.rst.

4.111 KVM_MEMORY_ENCRYPT_REG_REGION¶

This ioctl can be used to register a guest memory region which maycontain encrypted data (e.g. guest RAM, SMRAM etc).

It is used in the SEV-enabled guest. When encryption is enabled, a guestmemory region may contain encrypted data. The SEV memory encryptionengine uses a tweak such that two identical plaintext pages, each atdifferent locations will have differing ciphertexts. So swapping ormoving ciphertext of those pages will not result in plaintext beingswapped. So relocating (or migrating) physical backing pages for the SEVguest will require some additional steps.

Note: The current SEV key management spec does not provide commands toswap or migrate (move) ciphertext pages. Hence, for now we pin the guestmemory region registered with the ioctl.

4.112 KVM_MEMORY_ENCRYPT_UNREG_REGION¶

This ioctl can be used to unregister the guest memory region registeredwith KVM_MEMORY_ENCRYPT_REG_REGION ioctl above.

4.113 KVM_HYPERV_EVENTFD¶

This ioctl (un)registers an eventfd to receive notifications from the guest onthe specified Hyper-V connection id through the SIGNAL_EVENT hypercall, withoutcausing a user exit. SIGNAL_EVENT hypercall with non-zero event flag number(bits 24-31) still triggers a KVM_EXIT_HYPERV_HCALL user exit.

struct kvm_hyperv_eventfd {      __u32 conn_id;      __s32 fd;      __u32 flags;      __u32 padding[3];};

The conn_id field should fit within 24 bits:

#define KVM_HYPERV_CONN_ID_MASK               0x00ffffff

The acceptable values for the flags field are:

#define KVM_HYPERV_EVENTFD_DEASSIGN   (1 << 0)

4.114 KVM_GET_NESTED_STATE¶

Errors:

E2BIG

the total state size exceeds the value of ‘size’ specified bythe user; the size required will be written into size.

struct kvm_nested_state {      __u16 flags;      __u16 format;      __u32 size;      union {              struct kvm_vmx_nested_state_hdr vmx;              struct kvm_svm_nested_state_hdr svm;              /* Pad the header to 128 bytes.  */              __u8 pad[120];      } hdr;      union {              struct kvm_vmx_nested_state_data vmx[0];              struct kvm_svm_nested_state_data svm[0];      } data;};#define KVM_STATE_NESTED_GUEST_MODE           0x00000001#define KVM_STATE_NESTED_RUN_PENDING          0x00000002#define KVM_STATE_NESTED_EVMCS                0x00000004#define KVM_STATE_NESTED_FORMAT_VMX           0#define KVM_STATE_NESTED_FORMAT_SVM           1#define KVM_STATE_NESTED_VMX_VMCS_SIZE        0x1000#define KVM_STATE_NESTED_VMX_SMM_GUEST_MODE   0x00000001#define KVM_STATE_NESTED_VMX_SMM_VMXON        0x00000002

#define KVM_STATE_VMX_PREEMPTION_TIMER_DEADLINE 0x00000001

struct kvm_vmx_nested_state_hdr {

__u64 vmxon_pa;__u64 vmcs12_pa;

struct {

__u16 flags;

} smm;

__u32 flags;__u64 preemption_timer_deadline;

};

struct kvm_vmx_nested_state_data {

__u8 vmcs12[KVM_STATE_NESTED_VMX_VMCS_SIZE];__u8 shadow_vmcs12[KVM_STATE_NESTED_VMX_VMCS_SIZE];

};

This ioctl copies the vcpu’s nested virtualization state from the kernel touserspace.

The maximum size of the state can be retrieved by passing KVM_CAP_NESTED_STATEto the KVM_CHECK_EXTENSION ioctl().

4.115 KVM_SET_NESTED_STATE¶

This copies the vcpu’s kvm_nested_state struct from userspace to the kernel.For the definition of struct kvm_nested_state, see KVM_GET_NESTED_STATE.

4.116 KVM_(UN)REGISTER_COALESCED_MMIO¶

Coalesced I/O is a performance optimization that defers hardwareregister write emulation so that userspace exits are avoided. It istypically used to reduce the overhead of emulating frequently accessedhardware registers.

When a hardware register is configured for coalesced I/O, write accessesdo not exit to userspace and their value is recorded in a ring bufferthat is shared between kernel and userspace.

Coalesced I/O is used if one or more write accesses to a hardwareregister can be deferred until a read or a write to another hardwareregister on the same device. This last access will cause a vmexit anduserspace will process accesses from the ring buffer before emulatingit. That will avoid exiting to userspace on repeated writes.

Coalesced pio is based on coalesced mmio. There is little differencebetween coalesced mmio and pio except that coalesced pio records accessesto I/O ports.

4.117 KVM_CLEAR_DIRTY_LOG (vm ioctl)¶

/* for KVM_CLEAR_DIRTY_LOG */struct kvm_clear_dirty_log {      __u32 slot;      __u32 num_pages;      __u64 first_page;      union {              void __user *dirty_bitmap; /* one bit per page */              __u64 padding;      };};

The ioctl clears the dirty status of pages in a memory slot, according tothe bitmap that is passed in struct kvm_clear_dirty_log’s dirty_bitmapfield. Bit 0 of the bitmap corresponds to page “first_page” in thememory slot, and num_pages is the size in bits of the input bitmap.first_page must be a multiple of 64; num_pages must also be a multiple of64 unless first_page + num_pages is the size of the memory slot. For eachbit that is set in the input bitmap, the corresponding page is marked “clean”in KVM’s dirty bitmap, and dirty tracking is re-enabled for that page(for example via write-protection, or by clearing the dirty bit ina page table entry).

If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 specifiesthe address space for which you want to return the dirty bitmap.They must be less than the value that KVM_CHECK_EXTENSION returns forthe KVM_CAP_MULTI_ADDRESS_SPACE capability.

This ioctl is mostly useful when KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2is enabled; for more information, see the description of the capability.However, it can always be used as long as KVM_CHECK_EXTENSION confirmsthat KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 is present.

4.118 KVM_GET_SUPPORTED_HV_CPUID¶

struct kvm_cpuid2 {      __u32 nent;      __u32 padding;      struct kvm_cpuid_entry2 entries[0];};struct kvm_cpuid_entry2 {      __u32 function;      __u32 index;      __u32 flags;      __u32 eax;      __u32 ebx;      __u32 ecx;      __u32 edx;      __u32 padding[3];};

This ioctl returns x86 cpuid features leaves related to Hyper-V emulation inKVM. Userspace can use the information returned by this ioctl to constructcpuid information presented to guests consuming Hyper-V enlightenments (e.g.Windows or Hyper-V guests).

CPUID feature leaves returned by this ioctl are defined by Hyper-V Top LevelFunctional Specification (TLFS). These leaves can’t be obtained withKVM_GET_SUPPORTED_CPUID ioctl because some of them intersect with KVM featureleaves (0x40000000, 0x40000001).

Currently, the following list of CPUID leaves are returned:

• HYPERV_CPUID_VENDOR_AND_MAX_FUNCTIONS
• HYPERV_CPUID_INTERFACE
• HYPERV_CPUID_VERSION
• HYPERV_CPUID_FEATURES
• HYPERV_CPUID_ENLIGHTMENT_INFO
• HYPERV_CPUID_IMPLEMENT_LIMITS
• HYPERV_CPUID_NESTED_FEATURES

HYPERV_CPUID_NESTED_FEATURES leaf is only exposed when Enlightened VMCS wasenabled on the corresponding vCPU (KVM_CAP_HYPERV_ENLIGHTENED_VMCS).

Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structurewith the ‘nent’ field indicating the number of entries in the variable-sizearray ‘entries’. If the number of entries is too low to describe all Hyper-Vfeature leaves, an error (E2BIG) is returned. If the number is more or equalto the number of Hyper-V feature leaves, the ‘nent’ field is adjusted to thenumber of valid entries in the ‘entries’ array, which is then filled.

‘index’ and ‘flags’ fields in ‘struct kvm_cpuid_entry2’ are currently reserved,userspace should not expect to get any particular value there.

4.119 KVM_ARM_VCPU_FINALIZE¶

Errors:

EPERM	feature not enabled, needs configuration, or already finalized
EINVAL	feature unknown or not present

Recognised values for feature:

arm64

KVM_ARM_VCPU_SVE (requires KVM_CAP_ARM_SVE)

Finalizes the configuration of the specified vcpu feature.

The vcpu must already have been initialised, enabling the affected feature, bymeans of a successful KVM_ARM_VCPU_INIT call with the appropriate flag set infeatures[].

For affected vcpu features, this is a mandatory step that must be performedbefore the vcpu is fully usable.

Between KVM_ARM_VCPU_INIT and KVM_ARM_VCPU_FINALIZE, the feature may beconfigured by use of ioctls such as KVM_SET_ONE_REG. The exact configurationthat should be performaned and how to do it are feature-dependent.

Other calls that depend on a particular feature being finalized, such asKVM_RUN, KVM_GET_REG_LIST, KVM_GET_ONE_REG and KVM_SET_ONE_REG, will fail with-EPERM unless the feature has already been finalized by means of aKVM_ARM_VCPU_FINALIZE call.

See KVM_ARM_VCPU_INIT for details of vcpu features that require finalizationusing this ioctl.

4.120 KVM_SET_PMU_EVENT_FILTER¶

struct kvm_pmu_event_filter {      __u32 action;      __u32 nevents;      __u32 fixed_counter_bitmap;      __u32 flags;      __u32 pad[4];      __u64 events[0];};

This ioctl restricts the set of PMU events that the guest can program.The argument holds a list of events which will be allowed or denied.The eventsel+umask of each event the guest attempts to program is comparedagainst the events field to determine whether the guest should have access.The events field only controls general purpose counters; fixed purposecounters are controlled by the fixed_counter_bitmap.

No flags are defined yet, the field must be zero.

Valid values for ‘action’:

#define KVM_PMU_EVENT_ALLOW 0#define KVM_PMU_EVENT_DENY 1

4.121 KVM_PPC_SVM_OFF¶

Errors:

EINVAL	if ultravisor failed to terminate the secure guest
ENOMEM	if hypervisor failed to allocate new radix page tables for guest

This ioctl is used to turn off the secure mode of the guest or transitionthe guest from secure mode to normal mode. This is invoked when the guestis reset. This has no effect if called for a normal guest.

This ioctl issues an ultravisor call to terminate the secure guest,unpins the VPA pages and releases all the device pages that are used totrack the secure pages by hypervisor.

4.122 KVM_S390_NORMAL_RESET¶

This ioctl resets VCPU registers and control structures according tothe cpu reset definition in the POP (Principles Of Operation).

4.123 KVM_S390_INITIAL_RESET¶

This ioctl resets VCPU registers and control structures according tothe initial cpu reset definition in the POP. However, the cpu is notput into ESA mode. This reset is a superset of the normal reset.

4.124 KVM_S390_CLEAR_RESET¶

This ioctl resets VCPU registers and control structures according tothe clear cpu reset definition in the POP. However, the cpu is not putinto ESA mode. This reset is a superset of the initial reset.

4.125 KVM_S390_PV_COMMAND¶

struct kvm_pv_cmd {      __u32 cmd;      /* Command to be executed */      __u16 rc;       /* Ultravisor return code */      __u16 rrc;      /* Ultravisor return reason code */      __u64 data;     /* Data or address */      __u32 flags;    /* flags for future extensions. Must be 0 for now */      __u32 reserved[3];};

cmd values:

KVM_PV_ENABLE

Allocate memory and register the VM with the Ultravisor, therebydonating memory to the Ultravisor that will become inaccessible toKVM. All existing CPUs are converted to protected ones. After thiscommand has succeeded, any CPU added via hotplug will becomeprotected during its creation as well.

Errors:

EINTR

an unmasked signal is pending

KVM_PV_DISABLE

Deregister the VM from the Ultravisor and reclaim the memory thathad been donated to the Ultravisor, making it usable by the kernelagain. All registered VCPUs are converted back to non-protectedones.

KVM_PV_VM_SET_SEC_PARMS

Pass the image header from VM memory to the Ultravisor inpreparation of image unpacking and verification.

KVM_PV_VM_UNPACK

Unpack (protect and decrypt) a page of the encrypted boot image.

KVM_PV_VM_VERIFY

Verify the integrity of the unpacked image. Only if this succeeds,KVM is allowed to start protected VCPUs.

Note

For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR andKVM_EXIT_EPR the corresponding

Note

KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.

6.1 KVM_CAP_PPC_OSI¶

This capability enables interception of OSI hypercalls that otherwise wouldbe treated as normal system calls to be injected into the guest. OSI hypercallswere invented by Mac-on-Linux to have a standardized communication mechanismbetween the guest and the host.

When this capability is enabled, KVM_EXIT_OSI can occur.

6.2 KVM_CAP_PPC_PAPR¶

This capability enables interception of PAPR hypercalls. PAPR hypercalls aredone using the hypercall instruction “sc 1”.

It also sets the guest privilege level to “supervisor” mode. Usually the guestruns in “hypervisor” privilege mode with a few missing features.

In addition to the above, it changes the semantics of SDR1. In this mode, theHTAB address part of SDR1 contains an HVA instead of a GPA, as PAPR keeps theHTAB invisible to the guest.

When this capability is enabled, KVM_EXIT_PAPR_HCALL can occur.

6.3 KVM_CAP_SW_TLB¶

struct kvm_config_tlb {      __u64 params;      __u64 array;      __u32 mmu_type;      __u32 array_len;};

Configures the virtual CPU’s TLB array, establishing a shared memory areabetween userspace and KVM. The “params” and “array” fields are userspaceaddresses of mmu-type-specific data structures. The “array_len” field is ansafety mechanism, and should be set to the size in bytes of the memory thatuserspace has reserved for the array. It must be at least the size dictatedby “mmu_type” and “params”.

While KVM_RUN is active, the shared region is under control of KVM. Itscontents are undefined, and any modification by userspace results inboundedly undefined behavior.

On return from KVM_RUN, the shared region will reflect the current state ofthe guest’s TLB. If userspace makes any changes, it must call KVM_DIRTY_TLBto tell KVM which entries have been changed, prior to calling KVM_RUN againon this vcpu.

For mmu types KVM_MMU_FSL_BOOKE_NOHV and KVM_MMU_FSL_BOOKE_HV:

• The “params” field is of type “struct kvm_book3e_206_tlb_params”.
• The “array” field points to an array of type “structkvm_book3e_206_tlb_entry”.
• The array consists of all entries in the first TLB, followed by allentries in the second TLB.
• Within a TLB, entries are ordered first by increasing set number. Within aset, entries are ordered by way (increasing ESEL).
• The hash for determining set number in TLB0 is: (MAS2 >> 12) & (num_sets - 1)where “num_sets” is the tlb_sizes[] value divided by the tlb_ways[] value.
• The tsize field of mas1 shall be set to 4K on TLB0, even though thehardware ignores this value for TLB0.

6.4 KVM_CAP_S390_CSS_SUPPORT¶

This capability enables support for handling of channel I/O instructions.

TEST PENDING INTERRUPTION and the interrupt portion of TEST SUBCHANNEL arehandled in-kernel, while the other I/O instructions are passed to userspace.

When this capability is enabled, KVM_EXIT_S390_TSCH will occur on TESTSUBCHANNEL intercepts.

Note that even though this capability is enabled per-vcpu, the completevirtual machine is affected.

6.5 KVM_CAP_PPC_EPR¶

This capability enables or disables the delivery of interrupts through theexternal proxy facility.

When enabled (args[0] != 0), every time the guest gets an external interruptdelivered, it automatically exits into user space with a KVM_EXIT_EPR exitto receive the topmost interrupt vector.

When disabled (args[0] == 0), behavior is as if this facility is unsupported.

When this capability is enabled, KVM_EXIT_EPR can occur.

6.6 KVM_CAP_IRQ_MPIC¶

This capability connects the vcpu to an in-kernel MPIC device.

6.7 KVM_CAP_IRQ_XICS¶

This capability connects the vcpu to an in-kernel XICS device.

6.8 KVM_CAP_S390_IRQCHIP¶

This capability enables the in-kernel irqchip for s390. Please refer to“4.24 KVM_CREATE_IRQCHIP” for details.

6.9 KVM_CAP_MIPS_FPU¶

This capability allows the use of the host Floating Point Unit by the guest. Itallows the Config1.FP bit to be set to enable the FPU in the guest. Once this isdone theKVM_REG_MIPS_FPR_* andKVM_REG_MIPS_FCR_* registers can beaccessed (depending on the current guest FPU register mode), and the Status.FR,Config5.FRE bits are accessible via the KVM API and also from the guest,depending on them being supported by the FPU.

6.10 KVM_CAP_MIPS_MSA¶

This capability allows the use of the MIPS SIMD Architecture (MSA) by the guest.It allows the Config3.MSAP bit to be set to enable the use of MSA by the guest.Once this is done theKVM_REG_MIPS_VEC_* andKVM_REG_MIPS_MSA_*registers can be accessed, and the Config5.MSAEn bit is accessible via theKVM API and also from the guest.

6.74 KVM_CAP_SYNC_REGS¶

As described above in the kvm_sync_regs struct info in section 5 (kvm_run):KVM_CAP_SYNC_REGS “allow[s] userspace to access certain guest registerswithout having to call SET/GET_*REGS”. This reduces overhead by eliminatingrepeated ioctl calls for setting and/or getting register values. This isparticularly important when userspace is making synchronous guest statemodifications, e.g. when emulating and/or intercepting instructions inuserspace.

For s390 specifics, please refer to the source code.

For x86:

• the register sets to be copied out to kvm_run are selectableby userspace (rather that all sets being copied out for every exit).
• vcpu_events are available in addition to regs and sregs.

For x86, the ‘kvm_valid_regs’ field of struct kvm_run is overloaded tofunction as an input bit-array field set by userspace to indicate thespecific register sets to be copied out on the next exit.

To indicate when userspace has modified values that should be copied intothe vCPU, the all architecture bitarray field, ‘kvm_dirty_regs’ must be set.This is done using the same bitflags as for the ‘kvm_valid_regs’ field.If the dirty bit is not set, then the register set values will not be copiedinto the vCPU even if they’ve been modified.

Unused bitfields in the bitarrays must be set to zero.

struct kvm_sync_regs {      struct kvm_regs regs;      struct kvm_sregs sregs;      struct kvm_vcpu_events events;};

6.75 KVM_CAP_PPC_IRQ_XIVE¶

This capability connects the vcpu to an in-kernel XIVE device.

7.1 KVM_CAP_PPC_ENABLE_HCALL¶

This capability controls whether individual sPAPR hypercalls (hcalls)get handled by the kernel or not. Enabling or disabling in-kernelhandling of an hcall is effective across the VM. On creation, aninitial set of hcalls are enabled for in-kernel handling, whichconsists of those hcalls for which in-kernel handlers were implementedbefore this capability was implemented. If disabled, the kernel willnot to attempt to handle the hcall, but will always exit to userspaceto handle it. Note that it may not make sense to enable some anddisable others of a group of related hcalls, but KVM does not preventuserspace from doing that.

If the hcall number specified is not one that has an in-kernelimplementation, the KVM_ENABLE_CAP ioctl will fail with an EINVALerror.

7.2 KVM_CAP_S390_USER_SIGP¶

This capability controls which SIGP orders will be handled completely in userspace. With this capability enabled, all fast orders will be handled completelyin the kernel:

• SENSE
• SENSE RUNNING
• EXTERNAL CALL
• EMERGENCY SIGNAL
• CONDITIONAL EMERGENCY SIGNAL

All other orders will be handled completely in user space.

Only privileged operation exceptions will be checked for in the kernel (or evenin the hardware prior to interception). If this capability is not enabled, theold way of handling SIGP orders is used (partially in kernel and user space).

7.3 KVM_CAP_S390_VECTOR_REGISTERS¶

Allows use of the vector registers introduced with z13 processor, andprovides for the synchronization between host and user space. Willreturn -EINVAL if the machine does not support vectors.

7.4 KVM_CAP_S390_USER_STSI¶

This capability allows post-handlers for the STSI instruction. Afterinitial handling in the kernel, KVM exits to user space withKVM_EXIT_S390_STSI to allow user space to insert further data.

Before exiting to userspace, kvm handlers should fill in s390_stsi field ofvcpu->run:

struct {      __u64 addr;      __u8 ar;      __u8 reserved;      __u8 fc;      __u8 sel1;      __u16 sel2;} s390_stsi;@addr - guest address of STSI SYSIB@fc   - function code@sel1 - selector 1@sel2 - selector 2@ar   - access register number

KVM handlers should exit to userspace with rc = -EREMOTE.

7.5 KVM_CAP_SPLIT_IRQCHIP¶

Create a local apic for each processor in the kernel. This can be usedinstead of KVM_CREATE_IRQCHIP if the userspace VMM wishes to emulate theIOAPIC and PIC (and also the PIT, even though this has to be enabledseparately).

This capability also enables in kernel routing of interrupt requests;when KVM_CAP_SPLIT_IRQCHIP only routes of KVM_IRQ_ROUTING_MSI type areused in the IRQ routing table. The first args[0] MSI routes are reservedfor the IOAPIC pins. Whenever the LAPIC receives an EOI for these routes,a KVM_EXIT_IOAPIC_EOI vmexit will be reported to userspace.

Fails if VCPU has already been created, or if the irqchip is already in thekernel (i.e. KVM_CREATE_IRQCHIP has already been called).

7.6 KVM_CAP_S390_RI¶

Allows use of runtime-instrumentation introduced with zEC12 processor.Will return -EINVAL if the machine does not support runtime-instrumentation.Will return -EBUSY if a VCPU has already been created.

7.7 KVM_CAP_X2APIC_API¶

Valid feature flags in args[0] are:

#define KVM_X2APIC_API_USE_32BIT_IDS            (1ULL << 0)#define KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK  (1ULL << 1)

Enabling KVM_X2APIC_API_USE_32BIT_IDS changes the behavior ofKVM_SET_GSI_ROUTING, KVM_SIGNAL_MSI, KVM_SET_LAPIC, and KVM_GET_LAPIC,allowing the use of 32-bit APIC IDs. See KVM_CAP_X2APIC_API in theirrespective sections.

KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK must be enabled for x2APIC to workin logical mode or with more than 255 VCPUs. Otherwise, KVM treats 0xffas a broadcast even in x2APIC mode in order to support physical x2APICwithout interrupt remapping. This is undesirable in logical mode,where 0xff represents CPUs 0-7 in cluster 0.

7.8 KVM_CAP_S390_USER_INSTR0¶

With this capability enabled, all illegal instructions 0x0000 (2 bytes) willbe intercepted and forwarded to user space. User space can use thismechanism e.g. to realize 2-byte software breakpoints. The kernel willnot inject an operating exception for these instructions, user space hasto take care of that.

This capability can be enabled dynamically even if VCPUs were alreadycreated and are running.

7.9 KVM_CAP_S390_GS¶

Allows use of guarded storage for the KVM guest.

7.10 KVM_CAP_S390_AIS¶

Allow use of adapter-interruption suppression.:Returns: 0 on success; -EBUSY if a VCPU has already been created.

7.11 KVM_CAP_PPC_SMT¶

Enabling this capability on a VM provides userspace with a way to setthe desired virtual SMT mode (i.e. the number of virtual CPUs pervirtual core). The virtual SMT mode, vsmt_mode, must be a power of 2between 1 and 8. On POWER8, vsmt_mode must also be no greater thanthe number of threads per subcore for the host. Currently flags mustbe 0. A successful call to enable this capability will result invsmt_mode being returned when the KVM_CAP_PPC_SMT capability issubsequently queried for the VM. This capability is only supported byHV KVM, and can only be set before any VCPUs have been created.The KVM_CAP_PPC_SMT_POSSIBLE capability indicates which virtual SMTmodes are available.

7.12 KVM_CAP_PPC_FWNMI¶

With this capability a machine check exception in the guest addressspace will cause KVM to exit the guest with NMI exit reason. Thisenables QEMU to build error log and branch to guest kernel registeredmachine check handling routine. Without this capability KVM willbranch to guests’ 0x200 interrupt vector.

7.13 KVM_CAP_X86_DISABLE_EXITS¶

Valid bits in args[0] are:

#define KVM_X86_DISABLE_EXITS_MWAIT            (1 << 0)#define KVM_X86_DISABLE_EXITS_HLT              (1 << 1)#define KVM_X86_DISABLE_EXITS_PAUSE            (1 << 2)#define KVM_X86_DISABLE_EXITS_CSTATE           (1 << 3)

Enabling this capability on a VM provides userspace with a way to nolonger intercept some instructions for improved latency in someworkloads, and is suggested when vCPUs are associated to dedicatedphysical CPUs. More bits can be added in the future; userspace canjust pass the KVM_CHECK_EXTENSION result to KVM_ENABLE_CAP to disableall such vmexits.

Do not enable KVM_FEATURE_PV_UNHALT if you disable HLT exits.

7.14 KVM_CAP_S390_HPAGE_1M¶

With this capability the KVM support for memory backing with 1m pagesthrough hugetlbfs can be enabled for a VM. After the capability isenabled, cmma can’t be enabled anymore and pfmfi and the storage keyinterpretation are disabled. If cmma has already been enabled or thehpage module parameter is not set to 1, -EINVAL is returned.

While it is generally possible to create a huge page backed VM withoutthis capability, the VM will not be able to run.

7.15 KVM_CAP_MSR_PLATFORM_INFO¶

With this capability, a guest may read the MSR_PLATFORM_INFO MSR. Otherwise,a #GP would be raised when the guest tries to access. Currently, thiscapability does not enable write permissions of this MSR for the guest.

7.16 KVM_CAP_PPC_NESTED_HV¶

HV-KVM on POWER9 and later systems allows for “nested-HV”virtualization, which provides a way for a guest VM to run guests thatcan run using the CPU’s supervisor mode (privileged non-hypervisorstate). Enabling this capability on a VM depends on the CPU havingthe necessary functionality and on the facility being enabled with akvm-hv module parameter.

7.17 KVM_CAP_EXCEPTION_PAYLOAD¶

With this capability enabled, CR2 will not be modified prior to theemulated VM-exit when L1 intercepts a #PF exception that occurs inL2. Similarly, for kvm-intel only, DR6 will not be modified prior tothe emulated VM-exit when L1 intercepts a #DB exception that occurs inL2. As a result, when KVM_GET_VCPU_EVENTS reports a pending #PF (or#DB) exception for L2, exception.has_payload will be set and thefaulting address (or the new DR6 bits*) will be reported in theexception_payload field. Similarly, when userspace injects a #PF (or#DB) into L2 using KVM_SET_VCPU_EVENTS, it is expected to setexception.has_payload and to put the faulting address - or the new DR6bits[3] - in the exception_payload field.

This capability also enables exception.pending in structkvm_vcpu_events, which allows userspace to distinguish between pendingand injected exceptions.

7.18 KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2

Valid flags are:

#define KVM_DIRTY_LOG_MANUAL_PROTECT_ENABLE   (1 << 0)#define KVM_DIRTY_LOG_INITIALLY_SET           (1 << 1)

With KVM_DIRTY_LOG_MANUAL_PROTECT_ENABLE is set, KVM_GET_DIRTY_LOG will notautomatically clear and write-protect all pages that are returned as dirty.Rather, userspace will have to do this operation separately usingKVM_CLEAR_DIRTY_LOG.

At the cost of a slightly more complicated operation, this provides betterscalability and responsiveness for two reasons. First,KVM_CLEAR_DIRTY_LOG ioctl can operate on a 64-page granularity ratherthan requiring to sync a full memslot; this ensures that KVM does nottake spinlocks for an extended period of time. Second, in some cases alarge amount of time can pass between a call to KVM_GET_DIRTY_LOG anduserspace actually using the data in the page. Pages can be modifiedduring this time, which is inefficient for both the guest and userspace:the guest will incur a higher penalty due to write protection faults,while userspace can see false reports of dirty pages. Manual reprotectionhelps reducing this time, improving guest performance and reducing thenumber of dirty log false positives.

With KVM_DIRTY_LOG_INITIALLY_SET set, all the bits of the dirty bitmapwill be initialized to 1 when created. This also improves performance becausedirty logging can be enabled gradually in small chunks on the first callto KVM_CLEAR_DIRTY_LOG. KVM_DIRTY_LOG_INITIALLY_SET depends onKVM_DIRTY_LOG_MANUAL_PROTECT_ENABLE (it is also only available onx86 and arm64 for now).

KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 was previously available under the nameKVM_CAP_MANUAL_DIRTY_LOG_PROTECT, but the implementation had bugs that makeit hard or impossible to use it correctly. The availability ofKVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 signals that those bugs are fixed.Userspace should not try to use KVM_CAP_MANUAL_DIRTY_LOG_PROTECT.

7.19 KVM_CAP_PPC_SECURE_GUEST¶

This capability indicates that KVM is running on a host that hasultravisor firmware and thus can support a secure guest. On such asystem, a guest can ask the ultravisor to make it a secure guest,one whose memory is inaccessible to the host except for pages whichare explicitly requested to be shared with the host. The ultravisornotifies KVM when a guest requests to become a secure guest, and KVMhas the opportunity to veto the transition.

If present, this capability can be enabled for a VM, meaning that KVMwill allow the transition to secure guest mode. Otherwise KVM willveto the transition.

7.20 KVM_CAP_HALT_POLL¶

This capability overrides the kvm module parameter halt_poll_ns for thetarget VM.

VCPU polling allows a VCPU to poll for wakeup events instead of immediatelyscheduling during guest halts. The maximum time a VCPU can spend polling iscontrolled by the kvm module parameter halt_poll_ns. This capability allowsthe maximum halt time to specified on a per-VM basis, effectively overridingthe module parameter for the target VM.

8.1 KVM_CAP_PPC_HWRNG¶

This capability, if KVM_CHECK_EXTENSION indicates that it isavailable, means that the kernel has an implementation of theH_RANDOM hypercall backed by a hardware random-number generator.If present, the kernel H_RANDOM handler can be enabled for guest usewith the KVM_CAP_PPC_ENABLE_HCALL capability.

8.2 KVM_CAP_HYPERV_SYNIC¶

This capability, if KVM_CHECK_EXTENSION indicates that it isavailable, means that the kernel has an implementation of theHyper-V Synthetic interrupt controller(SynIC). Hyper-V SynIC isused to support Windows Hyper-V based guest paravirt drivers(VMBus).

In order to use SynIC, it has to be activated by setting thiscapability via KVM_ENABLE_CAP ioctl on the vcpu fd. Note that thiswill disable the use of APIC hardware virtualization even if supportedby the CPU, as it’s incompatible with SynIC auto-EOI behavior.

8.3 KVM_CAP_PPC_RADIX_MMU¶

This capability, if KVM_CHECK_EXTENSION indicates that it isavailable, means that the kernel can support guests using theradix MMU defined in Power ISA V3.00 (as implemented in the POWER9processor).

8.4 KVM_CAP_PPC_HASH_MMU_V3¶

This capability, if KVM_CHECK_EXTENSION indicates that it isavailable, means that the kernel can support guests using thehashed page table MMU defined in Power ISA V3.00 (as implemented inthe POWER9 processor), including in-memory segment tables.

8.5 KVM_CAP_MIPS_VZ¶

This capability, if KVM_CHECK_EXTENSION on the main kvm handle indicates thatit is available, means that full hardware assisted virtualization capabilitiesof the hardware are available for use through KVM. An appropriateKVM_VM_MIPS_* type must be passed to KVM_CREATE_VM to create a VM whichutilises it.

If KVM_CHECK_EXTENSION on a kvm VM handle indicates that this capability isavailable, it means that the VM is using full hardware assisted virtualizationcapabilities of the hardware. This is useful to check after creating a VM withKVM_VM_MIPS_DEFAULT.

The value returned by KVM_CHECK_EXTENSION should be compared against knownvalues (see below). All other values are reserved. This is to allow for thepossibility of other hardware assisted virtualization implementations whichmay be incompatible with the MIPS VZ ASE.

8.6 KVM_CAP_MIPS_TE¶

This capability, if KVM_CHECK_EXTENSION on the main kvm handle indicates thatit is available, means that the trap & emulate implementation is available torun guest code in user mode, even if KVM_CAP_MIPS_VZ indicates that hardwareassisted virtualisation is also available. KVM_VM_MIPS_TE (0) must be passedto KVM_CREATE_VM to create a VM which utilises it.

If KVM_CHECK_EXTENSION on a kvm VM handle indicates that this capability isavailable, it means that the VM is using trap & emulate.

8.7 KVM_CAP_MIPS_64BIT¶

This capability indicates the supported architecture type of the guest, i.e. thesupported register and address width.

The values returned when this capability is checked by KVM_CHECK_EXTENSION on akvm VM handle correspond roughly to the CP0_Config.AT register field, and shouldbe checked specifically against known values (see below). All other values arereserved.

8.9 KVM_CAP_ARM_USER_IRQ¶

This capability, if KVM_CHECK_EXTENSION indicates that it is available, meansthat if userspace creates a VM without an in-kernel interrupt controller, itwill be notified of changes to the output level of in-kernel emulated devices,which can generate virtual interrupts, presented to the VM.For such VMs, on every return to userspace, the kernelupdates the vcpu’s run->s.regs.device_irq_level field to represent the actualoutput level of the device.

Whenever kvm detects a change in the device output level, kvm guarantees atleast one return to userspace before running the VM. This exit could eitherbe a KVM_EXIT_INTR or any other exit event, like KVM_EXIT_MMIO. This way,userspace can always sample the device output level and re-compute the state ofthe userspace interrupt controller. Userspace should always check the stateof run->s.regs.device_irq_level on every kvm exit.The value in run->s.regs.device_irq_level can represent both level and edgetriggered interrupt signals, depending on the device. Edge triggered interruptsignals will exit to userspace with the bit in run->s.regs.device_irq_levelset exactly once per edge signal.

The field run->s.regs.device_irq_level is available independent ofrun->kvm_valid_regs or run->kvm_dirty_regs bits.

If KVM_CAP_ARM_USER_IRQ is supported, the KVM_CHECK_EXTENSION ioctl returns anumber larger than 0 indicating the version of this capability is implementedand thereby which bits in run->s.regs.device_irq_level can signal values.

Currently the following bits are defined for the device_irq_level bitmap:

KVM_CAP_ARM_USER_IRQ >= 1:  KVM_ARM_DEV_EL1_VTIMER -  EL1 virtual timer  KVM_ARM_DEV_EL1_PTIMER -  EL1 physical timer  KVM_ARM_DEV_PMU        -  ARM PMU overflow interrupt signal

Future versions of kvm may implement additional events. These will getindicated by returning a higher number from KVM_CHECK_EXTENSION and will belisted above.

8.10 KVM_CAP_PPC_SMT_POSSIBLE¶

Querying this capability returns a bitmap indicating the possiblevirtual SMT modes that can be set using KVM_CAP_PPC_SMT. If bit N(counting from the right) is set, then a virtual SMT mode of 2^N isavailable.

8.11 KVM_CAP_HYPERV_SYNIC2¶

This capability enables a newer version of Hyper-V Synthetic interruptcontroller (SynIC). The only difference with KVM_CAP_HYPERV_SYNIC is that KVMdoesn’t clear SynIC message and event flags pages when they are enabled bywriting to the respective MSRs.

8.12 KVM_CAP_HYPERV_VP_INDEX¶

This capability indicates that userspace can load HV_X64_MSR_VP_INDEX msr. Itsvalue is used to denote the target vcpu for a SynIC interrupt. Forcompatibilty, KVM initializes this msr to KVM’s internal vcpu index. When thiscapability is absent, userspace can still query this msr’s value.

8.13 KVM_CAP_S390_AIS_MIGRATION¶

This capability indicates if the flic device will be able to get/set theAIS states for migration via the KVM_DEV_FLIC_AISM_ALL attribute and allowsto discover this without having to create a flic device.

8.14 KVM_CAP_S390_PSW¶

This capability indicates that the PSW is exposed via the kvm_run structure.

8.15 KVM_CAP_S390_GMAP¶

This capability indicates that the user space memory used as guest mapping canbe anywhere in the user memory address space, as long as the memory slots arealigned and sized to a segment (1MB) boundary.

8.16 KVM_CAP_S390_COW¶

This capability indicates that the user space memory used as guest mapping canuse copy-on-write semantics as well as dirty pages tracking via read-only pagetables.

8.17 KVM_CAP_S390_BPB¶

This capability indicates that kvm will implement the interfaces to handlereset, migration and nested KVM for branch prediction blocking. The stflefacility 82 should not be provided to the guest without this capability.

8.18 KVM_CAP_HYPERV_TLBFLUSH¶

This capability indicates that KVM supports paravirtualized Hyper-V TLB Flushhypercalls:HvFlushVirtualAddressSpace, HvFlushVirtualAddressSpaceEx,HvFlushVirtualAddressList, HvFlushVirtualAddressListEx.

8.19 KVM_CAP_ARM_INJECT_SERROR_ESR¶

This capability indicates that userspace can specify (via theKVM_SET_VCPU_EVENTS ioctl) the syndrome value reported to the guest when ittakes a virtual SError interrupt exception.If KVM advertises this capability, userspace can only specify the ISS field forthe ESR syndrome. Other parts of the ESR, such as the EC are generated by theCPU when the exception is taken. If this virtual SError is taken to EL1 usingAArch64, this value will be reported in the ISS field of ESR_ELx.

See KVM_CAP_VCPU_EVENTS for more details.

8.20 KVM_CAP_HYPERV_SEND_IPI¶

This capability indicates that KVM supports paravirtualized Hyper-V IPI sendhypercalls:HvCallSendSyntheticClusterIpi, HvCallSendSyntheticClusterIpiEx.

8.21 KVM_CAP_HYPERV_DIRECT_TLBFLUSH¶

This capability indicates that KVM running on top of Hyper-V hypervisorenables Direct TLB flush for its guests meaning that TLB flushhypercalls are handled by Level 0 hypervisor (Hyper-V) bypassing KVM.Due to the different ABI for hypercall parameters between Hyper-V andKVM, enabling this capability effectively disables all hypercallhandling by KVM (as some KVM hypercall may be mistakenly treated as TLBflush hypercalls by Hyper-V) so userspace should disable KVM identificationin CPUID and only exposes Hyper-V identification. In this case, guestthinks it’s running on Hyper-V and only use Hyper-V hypercalls.

8.22 KVM_CAP_S390_VCPU_RESETS¶

This capability indicates that the KVM_S390_NORMAL_RESET andKVM_S390_CLEAR_RESET ioctls are available.

8.23 KVM_CAP_S390_PROTECTED¶

This capability indicates that the Ultravisor has been initialized andKVM can therefore start protected VMs.This capability governs the KVM_S390_PV_COMMAND ioctl and theKVM_MP_STATE_LOAD MP_STATE. KVM_SET_MP_STATE can fail for protectedguests when the state change is invalid.

8.24 KVM_CAP_STEAL_TIME¶

This capability indicates that KVM supports steal time accounting.When steal time accounting is supported it may be enabled witharchitecture-specific interfaces. This capability and the architecture-specific interfaces must be consistent, i.e. if one says the featureis supported, than the other should as well and vice versa. For arm64see Documentation/virt/kvm/devices/vcpu.rst “KVM_ARM_VCPU_PVTIME_CTRL”.For x86 see Documentation/virt/kvm/msr.rst “MSR_KVM_STEAL_TIME”.

8.25 KVM_CAP_S390_DIAG318¶

This capability enables a guest to set information about its control program(i.e. guest kernel type and version). The information is helpful duringsystem/firmware service events, providing additional data about the guestenvironments running on the machine.

The information is associated with the DIAGNOSE 0x318 instruction, which setsan 8-byte value consisting of a one-byte Control Program Name Code (CPNC) anda 7-byte Control Program Version Code (CPVC). The CPNC determines whatenvironment the control program is running in (e.g. Linux, z/VM…), and theCPVC is used for information specific to OS (e.g. Linux version, Linuxdistribution…)

If this capability is available, then the CPNC and CPVC can be synchronizedbetween KVM and userspace via the sync regs mechanism (KVM_SYNC_DIAG318).