api.txt

  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 that
is 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 of
that is the register group type, or coprocessor number:

arm64 core/FP-SIMD registers have the following id bit patterns. Note
that the size of the access is variable, as the kvm_regs structure
contains elements ranging from 32 to 128 bits. The index is a 32bit
value in the kvm_regs structure seen as a 32bit array.
  0x60x0 0000 0010 <index into the kvm_regs struct:16>

Specifically:
    Encoding            Register  Bits  kvm_regs member
----------------------------------------------------------------
  0x6030 0000 0010 0000 X0          64  regs.regs[0]
  0x6030 0000 0010 0002 X1          64  regs.regs[1]
    ...
  0x6030 0000 0010 003c X30         64  regs.regs[30]
  0x6030 0000 0010 003e SP          64  regs.sp
  0x6030 0000 0010 0040 PC          64  regs.pc
  0x6030 0000 0010 0042 PSTATE      64  regs.pstate
  0x6030 0000 0010 0044 SP_EL1      64  sp_el1
  0x6030 0000 0010 0046 ELR_EL1     64  elr_el1
  0x6030 0000 0010 0048 SPSR_EL1    64  spsr[KVM_SPSR_EL1] (alias SPSR_SVC)
  0x6030 0000 0010 004a SPSR_ABT    64  spsr[KVM_SPSR_ABT]
  0x6030 0000 0010 004c SPSR_UND    64  spsr[KVM_SPSR_UND]
  0x6030 0000 0010 004e SPSR_IRQ    64  spsr[KVM_SPSR_IRQ]
  0x6060 0000 0010 0050 SPSR_FIQ    64  spsr[KVM_SPSR_FIQ]
  0x6040 0000 0010 0054 V0         128  fp_regs.vregs[0]    (*)
  0x6040 0000 0010 0058 V1         128  fp_regs.vregs[1]    (*)
    ...
  0x6040 0000 0010 00d0 V31        128  fp_regs.vregs[31]   (*)
  0x6020 0000 0010 00d4 FPSR        32  fp_regs.fpsr
  0x6020 0000 0010 00d5 FPCR        32  fp_regs.fpcr

(*) These encodings are not accepted for SVE-enabled vcpus.  See
    KVM_ARM_VCPU_INIT.

    The equivalent register content can be accessed via bits [127:0] of
    the corresponding SVE Zn registers instead for vcpus that have SVE
    enabled (see below).

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>

WARNING:
     Two system register IDs do not follow the specified pattern.  These
     are KVM_REG_ARM_TIMER_CVAL and KVM_REG_ARM_TIMER_CNT, which map to
     system registers CNTV_CVAL_EL0 and CNTVCT_EL0 respectively.  These
     two had their values accidentally swapped, which means TIMER_CVAL is
     derived from the register encoding for CNTVCT_EL0 and TIMER_CNT is
     derived from the register encoding for CNTV_CVAL_EL0.  As this is
     API, it must remain this way.

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 with
ENOENT.  max_vq is the vcpu's maximum supported vector length in 128-bit
quadwords: see (**) 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 not
accessible until the vcpu's SVE configuration has been finalized
using KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE).  See KVM_ARM_VCPU_INIT
and KVM_ARM_VCPU_FINALIZE for more information about this procedure.

KVM_REG_ARM64_SVE_VLS is a pseudo-register that allows the set of vector
lengths supported by the vcpu to be discovered and configured by
userspace.  When transferred to or from user memory via KVM_GET_ONE_REG
or 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 as
follows:

__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 */

(**) The maximum value vq for which the above condition is true is
max_vq.  This is the maximum vector length available to the guest on
this vcpu, and determines which register slices are visible through
this ioctl interface.

(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 that
the host supports.

Userspace may subsequently modify it if desired until the vcpu's SVE
configuration is finalized using KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE).

Apart from simply removing all vector lengths from the host set that
exceed some value, support for arbitrarily chosen sets of vector lengths
is hardware-dependent and may not be available.  Attempting to configure
an invalid set of vector lengths via KVM_SET_ONE_REG will fail with
EINVAL.

After the vcpu's SVE configuration is finalized, further attempts to
write this register will fail with EPERM.


MIPS registers are mapped using the lower 32 bits.  The upper 16 of that is
the 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 bit
patterns 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 MIPS64
versions of the EntryLo registers regardless of the word size of the host
hardware, 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, and
the PFNX field starting at bit 30.

MIPS MAARs (see KVM_REG_MIPS_CP0_MAAR(*) above) have the following id bit
patterns:
  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 following
id bit patterns depending on the size of the register being accessed. They are
always accessed according to the current guest FPU mode (Status.FR and
Config5.FRE), i.e. as the guest would see them, and they become unpredictable
if the guest FPU mode is changed. MIPS SIMD Architecture (MSA) vector
registers (see KVM_REG_MIPS_VEC_128() above) have similar patterns as they
overlap 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 the
following id bit patterns:
  0x7020 0000 0003 01 <0:3> <reg:5>

MIPS MSA control registers (see KVM_REG_MIPS_MSA_{IR,CSR} above) have the
following id bit patterns:
  0x7020 0000 0003 02 <0:3> <reg:5>


4.69 KVM_GET_ONE_REG

Capability: KVM_CAP_ONE_REG
Architectures: all
Type: vcpu ioctl
Parameters: struct kvm_one_reg (in and out)
Returns: 0 on success, negative value on failure
Errors include:
  ENOENT:   no such register
  EINVAL:   invalid register ID, or no such register
  EPERM:    (arm64) register access not allowed before vcpu finalization
(These error codes are indicative only: do not rely on a specific error
code being returned in a specific situation.)

This ioctl allows to receive the value of a single register implemented
in a vcpu. The register to read is indicated by the "id" field of the
kvm_one_reg struct passed in. On success, the register value can be found
at the memory location pointed to by "addr".

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


4.70 KVM_KVMCLOCK_CTRL

Capability: KVM_CAP_KVMCLOCK_CTRL
Architectures: Any that implement pvclocks (currently x86 only)
Type: vcpu ioctl
Parameters: None
Returns: 0 on success, -1 on error

This signals to the host kernel that the specified guest is being paused by
userspace.  The host will set a flag in the pvclock structure that is checked
from the soft lockup watchdog.  The flag is part of the pvclock structure that
is shared between guest and host, specifically the second bit of the flags
field of the pvclock_vcpu_time_info structure.  It will be set exclusively by
the host and read/cleared exclusively by the guest.  The guest operation of
checking and clearing the flag must an atomic operation so
load-link/store-conditional, or equivalent must be used.  There are two cases
where the guest will clear the flag: when the soft lockup watchdog timer resets
itself or when a soft lockup is detected.  This ioctl can be called any time
after pausing the vcpu, but before it is resumed.


4.71 KVM_SIGNAL_MSI

Capability: KVM_CAP_SIGNAL_MSI
Architectures: x86 arm arm64
Type: vm ioctl
Parameters: struct kvm_msi (in)
Returns: >0 on delivery, 0 if guest blocked the MSI, and -1 on error

Directly inject a MSI message. Only valid with in-kernel irqchip that handles
MSI 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-VM
  KVM_CAP_MSI_DEVID capability advertises the requirement to provide
  the device ID.  If this capability is not available, userspace
  should 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 identifier
for the device that wrote the MSI message.  For PCI, this is usually a
BFD identifier in the lower 16 bits.

On x86, address_hi is ignored unless the KVM_X2APIC_API_USE_32BIT_IDS
feature 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 of
address_hi must be zero.


4.71 KVM_CREATE_PIT2

Capability: KVM_CAP_PIT2
Architectures: x86
Type: vm ioctl
Parameters: struct kvm_pit_config (in)
Returns: 0 on success, -1 on error

Creates an in-kernel device model for the i8254 PIT. This call is only valid
after enabling in-kernel irqchip support via KVM_CREATE_IRQCHIP. The following
parameters 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 it
exists, 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 of
this thread may have to be adjusted accordingly.

This IOCTL replaces the obsolete KVM_CREATE_PIT.


4.72 KVM_GET_PIT2

Capability: KVM_CAP_PIT_STATE2
Architectures: x86
Type: vm ioctl
Parameters: struct kvm_pit_state2 (out)
Returns: 0 on success, -1 on error

Retrieves the state of the in-kernel PIT model. Only valid after
KVM_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

Capability: KVM_CAP_PIT_STATE2
Architectures: x86
Type: vm ioctl
Parameters: struct kvm_pit_state2 (in)
Returns: 0 on success, -1 on error

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

Capability: KVM_CAP_PPC_GET_SMMU_INFO
Architectures: powerpc
Type: vm ioctl
Parameters: None
Returns: 0 on success, -1 on error

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

The structure contains some global information, followed by an
array 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 backing
        store page sizes. When not set, any page size in the list can
        be used regardless of how they are backed by userspace.

    - KVM_PPC_1T_SEGMENTS
        The emulated MMU supports 1T segments in addition to the
        standard 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 base
page sizes for a segment in increasing order. Each entry is defined
as 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 is
organized in increasing order, a lookup can stop when encoutering
such an entry.

The "slb_enc" field provides the encoding to use in the SLB for the
page size. The bits are in positions such as the value can directly
be OR'ed into the "vsid" argument of the slbmte instruction.

The "enc" array is a list which for each of those segment base page
size provides the list of supported actual page sizes (which can be
only larger or equal to the base page size), along with the
corresponding encoding in the hash PTE. Similarly, the array is
8 entries sorted by increasing sizes and an entry with a "0" shift
is 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 hash
PTE's RPN field (ie, it needs to be shifted left by 12 to OR it
into the hash PTE second double word).

4.75 KVM_IRQFD

Capability: KVM_CAP_IRQFD
Architectures: x86 s390 arm arm64
Type: vm ioctl
Parameters: struct kvm_irqfd (in)
Returns: 0 on success, -1 on error

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

With KVM_CAP_IRQFD_RESAMPLE, KVM_IRQFD supports a de-assert and notify
mechanism allowing emulation of level-triggered, irqfd-based
interrupts.  When KVM_IRQFD_FLAG_RESAMPLE is set the user must pass an
additional eventfd in the kvm_irqfd.resamplefd field.  When operating
in resample mode, posting of an interrupt through kvm_irq.fd asserts
the specified gsi in the irqchip.  When the irqchip is resampled, such
as from an EOI, the gsi is de-asserted and the user is notified via
kvm_irqfd.resamplefd.  It is the user's responsibility to re-queue
the interrupt if the device making use of it still requires service.
Note that closing the resamplefd is not sufficient to disable the
irqfd.  The KVM_IRQFD_FLAG_RESAMPLE is only necessary on assignment
and 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 MSI
  message and device ID are translated into an LPI (support restricted
  to GICv3 ITS in-kernel emulation).

4.76 KVM_PPC_ALLOCATE_HTAB

Capability: KVM_CAP_PPC_ALLOC_HTAB
Architectures: powerpc
Type: vm ioctl
Parameters: Pointer to u32 containing hash table order (in/out)
Returns: 0 on success, -1 on error

This requests the host kernel to allocate an MMU hash table for a
guest using the PAPR paravirtualization interface.  This only does
anything if the kernel is configured to use the Book 3S HV style of
virtualization.  Otherwise the capability doesn't exist and the ioctl
returns an ENOTTY error.  The rest of this description assumes Book 3S
HV.

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

The parameter is a pointer to a 32-bit unsigned integer variable
containing the order (log base 2) of the desired size of the hash
table, which must be between 18 and 46.  On successful return from the
ioctl, 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 a
default-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 hash
table will be freed and a new one allocated.  If this is ioctl is
called when a hash table has already been allocated of the same order
as specified, the kernel will clear out the existing hash table (zero
all HPTEs).  In either case, if the guest is using the virtualized
real-mode area (VRMA) facility, the kernel will re-create the VMRA
HPTEs on the next KVM_RUN of any vcpu.

4.77 KVM_S390_INTERRUPT

Capability: basic
Architectures: s390
Type: vm ioctl, vcpu ioctl
Parameters: struct kvm_s390_interrupt (in)
Returns: 0 on success, -1 on error

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 interrupt
			   parameters 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 an
    I/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 interrupt code in parm64 (note that
                           machine checks needing further payload are not
                           supported by this ioctl)

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

4.78 KVM_PPC_GET_HTAB_FD

Capability: KVM_CAP_PPC_HTAB_FD
Architectures: powerpc
Type: vm ioctl
Parameters: Pointer to struct kvm_get_htab_fd (in)
Returns: file descriptor number (>= 0) on success, -1 on error

This returns a file descriptor that can be used either to read out the
entries in the guest's hashed page table (HPT), or to write entries to
initialize the HPT.  The returned fd can only be written to if the
KVM_GET_HTAB_WRITE bit is set in the flags field of the argument, and
can only be read if that bit is clear.  The argument struct looks like
this:

/* 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 at
which 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 the
bolted bit set, if the KVM_GET_HTAB_BOLTED_ONLY bit is set, otherwise
all entries.  When the end of the HPT is reached, the read() will
return.  If read() is called again on the fd, it will start again from
the beginning of the HPT, but will only return HPT entries that have
changed since they were last read.

Data read or written is structured as a header (8 bytes) followed by a
series of valid HPT entries (16 bytes) each.  The header indicates how
many valid HPT entries there are and how many invalid entries follow
the valid entries.  The invalid entries are not represented explicitly
in 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 the
header; first `n_valid' valid entries with contents from the data
written, then `n_invalid' invalid entries, invalidating any previously
valid entries found.

4.79 KVM_CREATE_DEVICE

Capability: KVM_CAP_DEVICE_CTRL
Type: vm ioctl
Parameters: struct kvm_create_device (in/out)
Returns: 0 on success, -1 on error
Errors:
  ENODEV: The device type is unknown or unsupported
  EEXIST: Device already created, and this type of device may not
          be instantiated multiple times

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

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

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

Individual devices should not define flags.  Attributes should be used
for specifying any behavior that is not implied by the device type
number.

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

Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device,
  KVM_CAP_VCPU_ATTRIBUTES for vcpu device
Type: device ioctl, vm ioctl, vcpu ioctl
Parameters: struct kvm_device_attr
Returns: 0 on success, -1 on error
Errors:
  ENXIO:  The group or attribute is unknown/unsupported for this device
          or hardware support is missing.
  EPERM:  The attribute cannot (currently) be accessed this way
          (e.g. read-only attribute, or attribute that only makes
          sense 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.  The
semantics are device-specific.  See individual device documentation in
the "devices" directory.  As with ONE_REG, the size of the data
transferred 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

Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device,
  KVM_CAP_VCPU_ATTRIBUTES for vcpu device
Type: device ioctl, vm ioctl, vcpu ioctl
Parameters: struct kvm_device_attr
Returns: 0 on success, -1 on error
Errors:
  ENXIO:  The group or attribute is unknown/unsupported for this device
          or hardware support is missing.

Tests whether a device supports a particular attribute.  A successful
return indicates the attribute is implemented.  It does not necessarily
indicate that the attribute can be read or written in the device's
current state.  "addr" is ignored.

4.82 KVM_ARM_VCPU_INIT

Capability: basic
Architectures: arm, arm64
Type: vcpu ioctl
Parameters: struct kvm_vcpu_init (in)
Returns: 0 on success; -1 on error
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 what
optional features it should have.  This will cause a reset of the cpu
registers to their initial values.  If this is not called, KVM_RUN will
return ENOEXEC for that vcpu.

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

Userspace can call this function multiple times for a given vcpu, including
after the vcpu has been run. This will reset the vcpu to its initial
state. All calls to this function after the initial call must use the same
target 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 on
	  and 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 revision
          backward 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 authentication
	  for arm64 only.
	  Depends on KVM_CAP_ARM_PTRAUTH_ADDRESS.
	  If KVM_CAP_ARM_PTRAUTH_ADDRESS and KVM_CAP_ARM_PTRAUTH_GENERIC are
	  both present, then both KVM_ARM_VCPU_PTRAUTH_ADDRESS and
	  KVM_ARM_VCPU_PTRAUTH_GENERIC must be requested or neither must be
	  requested.

	- KVM_ARM_VCPU_PTRAUTH_GENERIC: Enables Generic Pointer authentication
	  for arm64 only.
	  Depends on KVM_CAP_ARM_PTRAUTH_GENERIC.
	  If KVM_CAP_ARM_PTRAUTH_ADDRESS and KVM_CAP_ARM_PTRAUTH_GENERIC are
	  both present, then both KVM_ARM_VCPU_PTRAUTH_ADDRESS and
	  KVM_ARM_VCPU_PTRAUTH_GENERIC must be requested or neither must be
	  requested.

	- 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: the
	        initial value of this pseudo-register indicates the best set of
	        vector 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 access
	        the scalable archietctural SVE registers
	        KVM_REG_ARM64_SVE_ZREG(), KVM_REG_ARM64_SVE_PREG() or
	        KVM_REG_ARM64_SVE_FFR;

	      - KVM_REG_ARM64_SVE_VLS may optionally be written using
	        KVM_SET_ONE_REG, to modify the set of vector lengths available
	        for the vcpu.

	   * After KVM_ARM_VCPU_FINALIZE(KVM_ARM_VCPU_SVE):

	      - the KVM_REG_ARM64_SVE_VLS pseudo-register is immutable, and can
	        no longer be written using KVM_SET_ONE_REG.

4.83 KVM_ARM_PREFERRED_TARGET

Capability: basic
Architectures: arm, arm64
Type: vm ioctl
Parameters: struct struct kvm_vcpu_init (out)
Returns: 0 on success; -1 on error
Errors:
  ENODEV:    no preferred target available for the host

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

The ioctl returns struct kvm_vcpu_init instance containing information
about preferred CPU target type and recommended features for it.  The
kvm_vcpu_init->features bitmap returned will have feature bits set if
the preferred target recommends setting these features, but this is
not mandatory.

The information returned by this ioctl can be used to prepare an instance
of struct kvm_vcpu_init for KVM_ARM_VCPU_INIT ioctl which will result in
in VCPU matching underlying host.


4.84 KVM_GET_REG_LIST

Capability: basic
Architectures: arm, arm64, mips
Type: vcpu ioctl
Parameters: struct kvm_reg_list (in/out)
Returns: 0 on success; -1 on error
Errors:
  E2BIG:     the reg index list is too big to fit in the array specified by
             the 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 the
KVM_GET_ONE_REG/KVM_SET_ONE_REG calls.


4.85 KVM_ARM_SET_DEVICE_ADDR (deprecated)

Capability: KVM_CAP_ARM_SET_DEVICE_ADDR
Architectures: arm, arm64
Type: vm ioctl
Parameters: struct kvm_arm_device_address (in)
Returns: 0 on success, -1 on error
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 guests
can access emulated or directly exposed devices, which the host kernel needs
to know about. The id field is an architecture specific identifier for a
specific device.

ARM/arm64 divides the id field into two parts, a device id and an
address 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 GIC
support for the hardware VGIC features, using KVM_ARM_DEVICE_VGIC_V2
as the device id.  When setting the base address for the guest's
mapping of the VGIC virtual CPU and distributor interface, the ioctl
must be called after calling KVM_CREATE_IRQCHIP, but before calling
KVM_RUN on any of the VCPUs.  Calling this ioctl twice for any of the
base addresses will return -EEXIST.

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


4.86 KVM_PPC_RTAS_DEFINE_TOKEN

Capability: KVM_CAP_PPC_RTAS
Architectures: ppc
Type: vm ioctl
Parameters: struct kvm_rtas_token_args
Returns: 0 on success, -1 on error

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

4.87 KVM_SET_GUEST_DEBUG

Capability: KVM_CAP_SET_GUEST_DEBUG
Architectures: x86, s390, ppc, arm64
Type: vcpu ioctl
Parameters: struct kvm_guest_debug (in)
Returns: 0 on success; -1 on error

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

Set up the processor specific debug registers and configure vcpu for
handling guest debug events. There are two parts to the structure, the
first a control bitfield indicates the type of debug events to handle
when 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 control
flags 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 breakpoints
are enabled in memory so we need to ensure breakpoint exceptions are