code:
.. SPDX-License-Identifier: GPL-2.0

=======================================
Internal ABI between the kernel and HYP
=======================================

This file documents the interaction between the Linux kernel and the
hypervisor layer when running Linux as a hypervisor (for example
KVM). It doesn't cover the interaction of the kernel with the
hypervisor when running as a guest (under Xen, KVM or any other
hypervisor), or any hypervisor-specific interaction when the kernel is
used as a host.

Note: KVM/arm has been removed from the kernel. The API described
here is still valid though, as it allows the kernel to kexec when
booted at HYP. It can also be used by a hypervisor other than KVM
if necessary.

On arm and arm64 (without VHE), the kernel doesn't run in hypervisor
mode, but still needs to interact with it, allowing a built-in
hypervisor to be either installed or torn down.

In order to achieve this, the kernel must be booted at HYP (arm) or
EL2 (arm64), allowing it to install a set of stubs before dropping to
SVC/EL1. These stubs are accessible by using a 'hvc #0' instruction,
and only act on individual CPUs.

Unless specified otherwise, any built-in hypervisor must implement
these functions (see arch/arm{,64}/include/asm/virt.h):

* ::

    r0/x0 = HVC_SET_VECTORS
    r1/x1 = vectors

  Set HVBAR/VBAR_EL2 to 'vectors' to enable a hypervisor. 'vectors'
  must be a physical address, and respect the alignment requirements
  of the architecture. Only implemented by the initial stubs, not by
  Linux hypervisors.

* ::

    r0/x0 = HVC_RESET_VECTORS

  Turn HYP/EL2 MMU off, and reset HVBAR/VBAR_EL2 to the initials
  stubs' exception vector value. This effectively disables an existing
  hypervisor.

* ::

    r0/x0 = HVC_SOFT_RESTART
    r1/x1 = restart address
    x2 = x0's value when entering the next payload (arm64)
    x3 = x1's value when entering the next payload (arm64)
    x4 = x2's value when entering the next payload (arm64)

  Mask all exceptions, disable the MMU, clear I+D bits, move the arguments
  into place (arm64 only), and jump to the restart address while at HYP/EL2.
  This hypercall is not expected to return to its caller.

* ::

    x0 = HVC_FINALISE_EL2 (arm64 only)

  Finish configuring EL2 depending on the command-line options,
  including an attempt to upgrade the kernel's exception level from
  EL1 to EL2 by enabling the VHE mode. This is conditioned by the CPU
  supporting VHE, the EL2 MMU being off, and VHE not being disabled by
  any other means (command line option, for example).

Any other value of r0/x0 triggers a hypervisor-specific handling,
which is not documented here.

The return value of a stub hypercall is held by r0/x0, and is 0 on
success, and HVC_STUB_ERR on error. A stub hypercall is allowed to
clobber any of the caller-saved registers (x0-x18 on arm64, r0-r3 and
ip on arm). It is thus recommended to use a function call to perform
the hypercall.

repo_name: angery/linux


code:
.. SPDX-License-Identifier: GPL-2.0

=======================
ARM Hypercall Interface
=======================

KVM handles the hypercall services as requested by the guests. New hypercall
services are regularly made available by the ARM specification or by KVM (as
vendor services) if they make sense from a virtualization point of view.

This means that a guest booted on two different versions of KVM can observe
two different "firmware" revisions. This could cause issues if a given guest
is tied to a particular version of a hypercall service, or if a migration
causes a different version to be exposed out of the blue to an unsuspecting
guest.

In order to remedy this situation, KVM exposes a set of "firmware
pseudo-registers" that can be manipulated using the GET/SET_ONE_REG
interface. These registers can be saved/restored by userspace, and set
to a convenient value as required.

The following registers are defined:

* KVM_REG_ARM_PSCI_VERSION:

  KVM implements the PSCI (Power State Coordination Interface)
  specification in order to provide services such as CPU on/off, reset
  and power-off to the guest.

  - Only valid if the vcpu has the KVM_ARM_VCPU_PSCI_0_2 feature set
    (and thus has already been initialized)
  - Returns the current PSCI version on GET_ONE_REG (defaulting to the
    highest PSCI version implemented by KVM and compatible with v0.2)
  - Allows any PSCI version implemented by KVM and compatible with
    v0.2 to be set with SET_ONE_REG
  - Affects the whole VM (even if the register view is per-vcpu)

* KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1:
    Holds the state of the firmware support to mitigate CVE-2017-5715, as
    offered by KVM to the guest via a HVC call. The workaround is described
    under SMCCC_ARCH_WORKAROUND_1 in [1].

  Accepted values are:

    KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_NOT_AVAIL:
      KVM does not offer
      firmware support for the workaround. The mitigation status for the
      guest is unknown.
    KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_AVAIL:
      The workaround HVC call is
      available to the guest and required for the mitigation.
    KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_NOT_REQUIRED:
      The workaround HVC call
      is available to the guest, but it is not needed on this VCPU.

* KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2:
    Holds the state of the firmware support to mitigate CVE-2018-3639, as
    offered by KVM to the guest via a HVC call. The workaround is described
    under SMCCC_ARCH_WORKAROUND_2 in [1]_.

  Accepted values are:

    KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_NOT_AVAIL:
      A workaround is not
      available. KVM does not offer firmware support for the workaround.
    KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_UNKNOWN:
      The workaround state is
      unknown. KVM does not offer firmware support for the workaround.
    KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_AVAIL:
      The workaround is available,
      and can be disabled by a vCPU. If
      KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_ENABLED is set, it is active for
      this vCPU.
    KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_NOT_REQUIRED:
      The workaround is always active on this vCPU or it is not needed.

Bitmap Feature Firmware Registers
---------------------------------

Contrary to the above registers, the following registers exposes the
hypercall services in the form of a feature-bitmap to the userspace. This
bitmap is translated to the services that are available to the guest.
There is a register defined per service call owner and can be accessed via
GET/SET_ONE_REG interface.

By default, these registers are set with the upper limit of the features
that are supported. This way userspace can discover all the usable
hypercall services via GET_ONE_REG. The user-space can write-back the
desired bitmap back via SET_ONE_REG. The features for the registers that
are untouched, probably because userspace isn't aware of them, will be
exposed as is to the guest.

Note that KVM will not allow the userspace to configure the registers
anymore once any of the vCPUs has run at least once. Instead, it will
return a -EBUSY.

The pseudo-firmware bitmap register are as follows:

* KVM_REG_ARM_STD_BMAP:
    Controls the bitmap of the ARM Standard Secure Service Calls.

  The following bits are accepted:

    Bit-0: KVM_REG_ARM_STD_BIT_TRNG_V1_0:
      The bit represents the services offered under v1.0 of ARM True Random
      Number Generator (TRNG) specification, ARM DEN0098.

* KVM_REG_ARM_STD_HYP_BMAP:
    Controls the bitmap of the ARM Standard Hypervisor Service Calls.

  The following bits are accepted:

    Bit-0: KVM_REG_ARM_STD_HYP_BIT_PV_TIME:
      The bit represents the Paravirtualized Time service as represented by
      ARM DEN0057A.

* KVM_REG_ARM_VENDOR_HYP_BMAP:
    Controls the bitmap of the Vendor specific Hypervisor Service Calls.

  The following bits are accepted:

    Bit-0: KVM_REG_ARM_VENDOR_HYP_BIT_FUNC_FEAT
      The bit represents the ARM_SMCCC_VENDOR_HYP_KVM_FEATURES_FUNC_ID
      and ARM_SMCCC_VENDOR_HYP_CALL_UID_FUNC_ID function-ids.

    Bit-1: KVM_REG_ARM_VENDOR_HYP_BIT_PTP:
      The bit represents the Precision Time Protocol KVM service.

Errors:

    =======  =============================================================
    -ENOENT   Unknown register accessed.
    -EBUSY    Attempt a 'write' to the register after the VM has started.
    -EINVAL   Invalid bitmap written to the register.
    =======  =============================================================

.. [1] https://developer.arm.com/-/media/developer/pdf/ARM_DEN_0070A_Firmware_interfaces_for_mitigating_CVE-2017-5715.pdf


code:
.. SPDX-License-Identifier: GPL-2.0

===
ARM
===

.. toctree::
   :maxdepth: 2

   hyp-abi
   hypercalls
   pvtime
   ptp_kvm


code:
.. SPDX-License-Identifier: GPL-2.0

PTP_KVM support for arm/arm64
=============================

PTP_KVM is used for high precision time sync between host and guests.
It relies on transferring the wall clock and counter value from the
host to the guest using a KVM-specific hypercall.

* ARM_SMCCC_VENDOR_HYP_KVM_PTP_FUNC_ID: 0x86000001

This hypercall uses the SMC32/HVC32 calling convention:

ARM_SMCCC_VENDOR_HYP_KVM_PTP_FUNC_ID
    ==============    ========    =====================================
    Function ID:      (uint32)    0x86000001
    Arguments:        (uint32)    KVM_PTP_VIRT_COUNTER(0)
                                  KVM_PTP_PHYS_COUNTER(1)
    Return Values:    (int32)     NOT_SUPPORTED(-1) on error, or
                      (uint32)    Upper 32 bits of wall clock time (r0)
                      (uint32)    Lower 32 bits of wall clock time (r1)
                      (uint32)    Upper 32 bits of counter (r2)
                      (uint32)    Lower 32 bits of counter (r3)
    Endianness:                   No Restrictions.
    ==============    ========    =====================================


code:
.. SPDX-License-Identifier: GPL-2.0

Paravirtualized time support for arm64
======================================

Arm specification DEN0057/A defines a standard for paravirtualised time
support for AArch64 guests:

https://developer.arm.com/docs/den0057/a

KVM/arm64 implements the stolen time part of this specification by providing
some hypervisor service calls to support a paravirtualized guest obtaining a
view of the amount of time stolen from its execution.

Two new SMCCC compatible hypercalls are defined:

* PV_TIME_FEATURES: 0xC5000020
* PV_TIME_ST:       0xC5000021

These are only available in the SMC64/HVC64 calling convention as
paravirtualized time is not available to 32 bit Arm guests. The existence of
the PV_TIME_FEATURES hypercall should be probed using the SMCCC 1.1
ARCH_FEATURES mechanism before calling it.

PV_TIME_FEATURES

    ============= ========    =================================================
    Function ID:  (uint32)    0xC5000020
    PV_call_id:   (uint32)    The function to query for support.
                              Currently only PV_TIME_ST is supported.
    Return value: (int64)     NOT_SUPPORTED (-1) or SUCCESS (0) if the relevant
                              PV-time feature is supported by the hypervisor.
    ============= ========    =================================================

PV_TIME_ST

    ============= ========    ==============================================
    Function ID:  (uint32)    0xC5000021
    Return value: (int64)     IPA of the stolen time data structure for this
                              VCPU. On failure:
                              NOT_SUPPORTED (-1)
    ============= ========    ==============================================

The IPA returned by PV_TIME_ST should be mapped by the guest as normal memory
with inner and outer write back caching attributes, in the inner shareable
domain. A total of 16 bytes from the IPA returned are guaranteed to be
meaningfully filled by the hypervisor (see structure below).

PV_TIME_ST returns the structure for the calling VCPU.

Stolen Time
-----------

The structure pointed to by the PV_TIME_ST hypercall is as follows:

+-------------+-------------+-------------+----------------------------+
| Field       | Byte Length | Byte Offset | Description                |
+=============+=============+=============+============================+
| Revision    |      4      |      0      | Must be 0 for version 1.0  |
+-------------+-------------+-------------+----------------------------+
| Attributes  |      4      |      4      | Must be 0                  |
+-------------+-------------+-------------+----------------------------+
| Stolen time |      8      |      8      | Stolen time in unsigned    |
|             |             |             | nanoseconds indicating how |
|             |             |             | much time this VCPU thread |
|             |             |             | was involuntarily not      |
|             |             |             | running on a physical CPU. |
+-------------+-------------+-------------+----------------------------+

All values in the structure are stored little-endian.

The structure will be updated by the hypervisor prior to scheduling a VCPU. It
will be present within a reserved region of the normal memory given to the
guest. The guest should not attempt to write into this memory. There is a
structure per VCPU of the guest.

It is advisable that one or more 64k pages are set aside for the purpose of
these structures and not used for other purposes, this enables the guest to map
the region using 64k pages and avoids conflicting attributes with other memory.

For the user space interface see
:ref:`Documentation/virt/kvm/devices/vcpu.rst <kvm_arm_vcpu_pvtime_ctrl>`.


code: This directory contains specific device bindings for KVM_CAP_DEVICE_CTRL.

path: Documentation/virt/kvm/devices/README


code:
.. SPDX-License-Identifier: GPL-2.0

===============================================
ARM Virtual Interrupt Translation Service (ITS)
===============================================

Device types supported:
  KVM_DEV_TYPE_ARM_VGIC_ITS    ARM Interrupt Translation Service Controller

The ITS allows MSI(-X) interrupts to be injected into guests. This extension is
optional.  Creating a virtual ITS controller also requires a host GICv3 (see
arm-vgic-v3.txt), but does not depend on having physical ITS controllers.

There can be multiple ITS controllers per guest, each of them has to have
a separate, non-overlapping MMIO region.

Groups
======

KVM_DEV_ARM_VGIC_GRP_ADDR
-------------------------

  Attributes:
    KVM_VGIC_ITS_ADDR_TYPE (rw, 64-bit)
      Base address in the guest physical address space of the GICv3 ITS
      control register frame.
      This address needs to be 64K aligned and the region covers 128K.

  Errors:

    =======  =================================================
    -E2BIG   Address outside of addressable IPA range
    -EINVAL  Incorrectly aligned address
    -EEXIST  Address already configured
    -EFAULT  Invalid user pointer for attr->addr.
    -ENODEV  Incorrect attribute or the ITS is not supported.
    =======  =================================================

KVM_DEV_ARM_VGIC_GRP_CTRL
-------------------------

  Attributes:
    KVM_DEV_ARM_VGIC_CTRL_INIT
      request the initialization of the ITS, no additional parameter in
      kvm_device_attr.addr.

    KVM_DEV_ARM_ITS_CTRL_RESET
      reset the ITS, no additional parameter in kvm_device_attr.addr.
      See "ITS Reset State" section.

    KVM_DEV_ARM_ITS_SAVE_TABLES
      save the ITS table data into guest RAM, at the location provisioned
      by the guest in corresponding registers/table entries. Should userspace
      require a form of dirty tracking to identify which pages are modified
      by the saving process, it should use a bitmap even if using another
      mechanism to track the memory dirtied by the vCPUs.

      The layout of the tables in guest memory defines an ABI. The entries
      are laid out in little endian format as described in the last paragraph.

    KVM_DEV_ARM_ITS_RESTORE_TABLES
      restore the ITS tables from guest RAM to ITS internal structures.

      The GICV3 must be restored before the ITS and all ITS registers but
      the GITS_CTLR must be restored before restoring the ITS tables.

      The GITS_IIDR read-only register must also be restored before
      calling KVM_DEV_ARM_ITS_RESTORE_TABLES as the IIDR revision field
      encodes the ABI revision.

      The expected ordering when restoring the GICv3/ITS is described in section
      "ITS Restore Sequence".

  Errors:

    =======  ==========================================================
     -ENXIO  ITS not properly configured as required prior to setting
             this attribute
    -ENOMEM  Memory shortage when allocating ITS internal data
    -EINVAL  Inconsistent restored data
    -EFAULT  Invalid guest ram access
    -EBUSY   One or more VCPUS are running
    -EACCES  The virtual ITS is backed by a physical GICv4 ITS, and the
	     state is not available without GICv4.1
    =======  ==========================================================

KVM_DEV_ARM_VGIC_GRP_ITS_REGS
-----------------------------

  Attributes:
      The attr field of kvm_device_attr encodes the offset of the
      ITS register, relative to the ITS control frame base address
      (ITS_base).

      kvm_device_attr.addr points to a __u64 value whatever the width
      of the addressed register (32/64 bits). 64 bit registers can only
      be accessed with full length.

      Writes to read-only registers are ignored by the kernel except for:

      - GITS_CREADR. It must be restored otherwise commands in the queue
        will be re-executed after restoring CWRITER. GITS_CREADR must be
        restored before restoring the GITS_CTLR which is likely to enable the
        ITS. Also it must be restored after GITS_CBASER since a write to
        GITS_CBASER resets GITS_CREADR.
      - GITS_IIDR. The Revision field encodes the table layout ABI revision.
        In the future we might implement direct injection of virtual LPIs.
        This will require an upgrade of the table layout and an evolution of
        the ABI. GITS_IIDR must be restored before calling
        KVM_DEV_ARM_ITS_RESTORE_TABLES.

      For other registers, getting or setting a register has the same
      effect as reading/writing the register on real hardware.

  Errors:

    =======  ====================================================
    -ENXIO   Offset does not correspond to any supported register
    -EFAULT  Invalid user pointer for attr->addr
    -EINVAL  Offset is not 64-bit aligned
    -EBUSY   one or more VCPUS are running
    =======  ====================================================

ITS Restore Sequence:
---------------------

The following ordering must be followed when restoring the GIC and the ITS:

a) restore all guest memory and create vcpus
b) restore all redistributors
c) provide the ITS base address
   (KVM_DEV_ARM_VGIC_GRP_ADDR)
d) restore the ITS in the following order:

     1. Restore GITS_CBASER
     2. Restore all other ``GITS_`` registers, except GITS_CTLR!
     3. Load the ITS table data (KVM_DEV_ARM_ITS_RESTORE_TABLES)
     4. Restore GITS_CTLR

Then vcpus can be started.

ITS Table ABI REV0:
-------------------

 Revision 0 of the ABI only supports the features of a virtual GICv3, and does
 not support a virtual GICv4 with support for direct injection of virtual
 interrupts for nested hypervisors.

 The device table and ITT are indexed by the DeviceID and EventID,
 respectively. The collection table is not indexed by CollectionID, and the
 entries in the collection are listed in no particular order.
 All entries are 8 bytes.

 Device Table Entry (DTE)::

   bits:     | 63| 62 ... 49 | 48 ... 5 | 4 ... 0 |
   values:   | V |   next    | ITT_addr |  Size   |

 where:

 - V indicates whether the entry is valid. If not, other fields
   are not meaningful.
 - next: equals to 0 if this entry is the last one; otherwise it
   corresponds to the DeviceID offset to the next DTE, capped by
   2^14 -1.
 - ITT_addr matches bits [51:8] of the ITT address (256 Byte aligned).
 - Size specifies the supported number of bits for the EventID,
   minus one

 Collection Table Entry (CTE)::

   bits:     | 63| 62 ..  52  | 51 ... 16 | 15  ...   0 |
   values:   | V |    RES0    |  RDBase   |    ICID     |

 where:

 - V indicates whether the entry is valid. If not, other fields are
   not meaningful.
 - RES0: reserved field with Should-Be-Zero-or-Preserved behavior.
 - RDBase is the PE number (GICR_TYPER.Processor_Number semantic),
 - ICID is the collection ID

 Interrupt Translation Entry (ITE)::

   bits:     | 63 ... 48 | 47 ... 16 | 15 ... 0 |
   values:   |    next   |   pINTID  |  ICID    |

 where:

 - next: equals to 0 if this entry is the last one; otherwise it corresponds
   to the EventID offset to the next ITE capped by 2^16 -1.
 - pINTID is the physical LPI ID; if zero, it means the entry is not valid
   and other fields are not meaningful.
 - ICID is the collection ID

ITS Reset State:
----------------

RESET returns the ITS to the same state that it was when first created and
initialized. When the RESET command returns, the following things are
guaranteed:

- The ITS is not enabled and quiescent
  GITS_CTLR.Enabled = 0 .Quiescent=1
- There is no internally cached state
- No collection or device table are used
  GITS_BASER<n>.Valid = 0
- GITS_CBASER = 0, GITS_CREADR = 0, GITS_CWRITER = 0
- The ABI version is unchanged and remains the one set when the ITS
  device was first created.


code:
.. SPDX-License-Identifier: GPL-2.0

==============================================================
ARM Virtual Generic Interrupt Controller v3 and later (VGICv3)
==============================================================

Device types supported:
  - KVM_DEV_TYPE_ARM_VGIC_V3     ARM Generic Interrupt Controller v3.0

Only one VGIC instance may be instantiated through this API.  The created VGIC
will act as the VM interrupt controller, requiring emulated user-space devices
to inject interrupts to the VGIC instead of directly to CPUs.  It is not
possible to create both a GICv3 and GICv2 on the same VM.

Creating a guest GICv3 device requires a host GICv3 as well.

Groups:
  KVM_DEV_ARM_VGIC_GRP_ADDR
   Attributes:

    KVM_VGIC_V3_ADDR_TYPE_DIST (rw, 64-bit)
      Base address in the guest physical address space of the GICv3 distributor
      register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.
      This address needs to be 64K aligned and the region covers 64 KByte.

    KVM_VGIC_V3_ADDR_TYPE_REDIST (rw, 64-bit)
      Base address in the guest physical address space of the GICv3
      redistributor register mappings. There are two 64K pages for each
      VCPU and all of the redistributor pages are contiguous.
      Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.
      This address needs to be 64K aligned.

    KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION (rw, 64-bit)
      The attribute data pointed to by kvm_device_attr.addr is a __u64 value::

        bits:     | 63   ....  52  |  51   ....   16 | 15 - 12  |11 - 0
        values:   |     count      |       base      |  flags   | index

      - index encodes the unique redistributor region index
      - flags: reserved for future use, currently 0
      - base field encodes bits [51:16] of the guest physical base address
        of the first redistributor in the region.
      - count encodes the number of redistributors in the region. Must be
        greater than 0.

      There are two 64K pages for each redistributor in the region and
      redistributors are laid out contiguously within the region. Regions
      are filled with redistributors in the index order. The sum of all
      region count fields must be greater than or equal to the number of
      VCPUs. Redistributor regions must be registered in the incremental
      index order, starting from index 0.

      The characteristics of a specific redistributor region can be read
      by presetting the index field in the attr data.
      Only valid for KVM_DEV_TYPE_ARM_VGIC_V3.

  It is invalid to mix calls with KVM_VGIC_V3_ADDR_TYPE_REDIST and
  KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION attributes.

  Errors:

    =======  =============================================================
    -E2BIG   Address outside of addressable IPA range
    -EINVAL  Incorrectly aligned address, bad redistributor region
             count/index, mixed redistributor region attribute usage
    -EEXIST  Address already configured
    -ENOENT  Attempt to read the characteristics of a non existing
             redistributor region
    -ENXIO   The group or attribute is unknown/unsupported for this device
             or hardware support is missing.
    -EFAULT  Invalid user pointer for attr->addr.
    =======  =============================================================

  KVM_DEV_ARM_VGIC_GRP_DIST_REGS, KVM_DEV_ARM_VGIC_GRP_REDIST_REGS
   Attributes:

    The attr field of kvm_device_attr encodes two values::

      bits:     | 63   ....  32  |  31   ....    0 |
      values:   |      mpidr     |      offset     |

    All distributor regs are (rw, 32-bit) and kvm_device_attr.addr points to a
    __u32 value.  64-bit registers must be accessed by separately accessing the
    lower and higher word.

    Writes to read-only registers are ignored by the kernel.

    KVM_DEV_ARM_VGIC_GRP_DIST_REGS accesses the main distributor registers.
    KVM_DEV_ARM_VGIC_GRP_REDIST_REGS accesses the redistributor of the CPU
    specified by the mpidr.

    The offset is relative to the "[Re]Distributor base address" as defined
    in the GICv3/4 specs.  Getting or setting such a register has the same
    effect as reading or writing the register on real hardware, except for the
    following registers: GICD_STATUSR, GICR_STATUSR, GICD_ISPENDR,
    GICR_ISPENDR0, GICD_ICPENDR, and GICR_ICPENDR0.  These registers behave
    differently when accessed via this interface compared to their
    architecturally defined behavior to allow software a full view of the
    VGIC's internal state.

    The mpidr field is used to specify which
    redistributor is accessed.  The mpidr is ignored for the distributor.

    The mpidr encoding is based on the affinity information in the
    architecture defined MPIDR, and the field is encoded as follows::

      | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
      |    Aff3    |    Aff2    |    Aff1    |    Aff0    |

    Note that distributor fields are not banked, but return the same value
    regardless of the mpidr used to access the register.

    GICD_IIDR.Revision is updated when the KVM implementation is changed in a
    way directly observable by the guest or userspace.  Userspace should read
    GICD_IIDR from KVM and write back the read value to confirm its expected
    behavior is aligned with the KVM implementation.  Userspace should set
    GICD_IIDR before setting any other registers to ensure the expected
    behavior.

    The GICD_STATUSR and GICR_STATUSR registers are architecturally defined such
    that a write of a clear bit has no effect, whereas a write with a set bit
    clears that value.  To allow userspace to freely set the values of these two
    registers, setting the attributes with the register offsets for these two
    registers simply sets the non-reserved bits to the value written.

    Accesses (reads and writes) to the GICD_ISPENDR register region and
    GICR_ISPENDR0 registers get/set the value of the latched pending state for
    the interrupts.

    This is identical to the value returned by a guest read from ISPENDR for an
    edge triggered interrupt, but may differ for level triggered interrupts.
    For edge triggered interrupts, once an interrupt becomes pending (whether
    because of an edge detected on the input line or because of a guest write
    to ISPENDR) this state is "latched", and only cleared when either the
    interrupt is activated or when the guest writes to ICPENDR. A level
    triggered interrupt may be pending either because the level input is held
    high by a device, or because of a guest write to the ISPENDR register. Only
    ISPENDR writes are latched; if the device lowers the line level then the
    interrupt is no longer pending unless the guest also wrote to ISPENDR, and
    conversely writes to ICPENDR or activations of the interrupt do not clear
    the pending status if the line level is still being held high.  (These
    rules are documented in the GICv3 specification descriptions of the ICPENDR
    and ISPENDR registers.) For a level triggered interrupt the value accessed
    here is that of the latch which is set by ISPENDR and cleared by ICPENDR or
    interrupt activation, whereas the value returned by a guest read from
    ISPENDR is the logical OR of the latch value and the input line level.

    Raw access to the latch state is provided to userspace so that it can save
    and restore the entire GIC internal state (which is defined by the
    combination of the current input line level and the latch state, and cannot
    be deduced from purely the line level and the value of the ISPENDR
    registers).

    Accesses to GICD_ICPENDR register region and GICR_ICPENDR0 registers have
    RAZ/WI semantics, meaning that reads always return 0 and writes are always
    ignored.

  Errors:

    ======  =====================================================
    -ENXIO  Getting or setting this register is not yet supported
    -EBUSY  One or more VCPUs are running
    ======  =====================================================

  KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS
   Attributes:

    The attr field of kvm_device_attr encodes two values::

      bits:     | 63      ....       32 | 31  ....  16 | 15  ....  0 |
      values:   |         mpidr         |      RES     |    instr    |

    The mpidr field encodes the CPU ID based on the affinity information in the
    architecture defined MPIDR, and the field is encoded as follows::

      | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
      |    Aff3    |    Aff2    |    Aff1    |    Aff0    |

    The instr field encodes the system register to access based on the fields
    defined in the A64 instruction set encoding for system register access
    (RES means the bits are reserved for future use and should be zero)::

      | 15 ... 14 | 13 ... 11 | 10 ... 7 | 6 ... 3 | 2 ... 0 |
      |   Op 0    |    Op1    |    CRn   |   CRm   |   Op2   |

    All system regs accessed through this API are (rw, 64-bit) and
    kvm_device_attr.addr points to a __u64 value.

    KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS accesses the CPU interface registers for the
    CPU specified by the mpidr field.

    CPU interface registers access is not implemented for AArch32 mode.
    Error -ENXIO is returned when accessed in AArch32 mode.

  Errors:

    =======  =====================================================
    -ENXIO   Getting or setting this register is not yet supported
    -EBUSY   VCPU is running
    -EINVAL  Invalid mpidr or register value supplied
    =======  =====================================================

  KVM_DEV_ARM_VGIC_GRP_NR_IRQS
   Attributes:

    A value describing the number of interrupts (SGI, PPI and SPI) for
    this GIC instance, ranging from 64 to 1024, in increments of 32.

    kvm_device_attr.addr points to a __u32 value.

  Errors:

    =======  ======================================
    -EINVAL  Value set is out of the expected range
    -EBUSY   Value has already be set.
    =======  ======================================

  KVM_DEV_ARM_VGIC_GRP_CTRL
   Attributes:

    KVM_DEV_ARM_VGIC_CTRL_INIT
      request the initialization of the VGIC, no additional parameter in
      kvm_device_attr.addr. Must be called after all VCPUs have been created.
    KVM_DEV_ARM_VGIC_SAVE_PENDING_TABLES
      save all LPI pending bits into guest RAM pending tables.

      The first kB of the pending table is not altered by this operation.

  Errors:

    =======  ========================================================
    -ENXIO   VGIC not properly configured as required prior to calling
             this attribute
    -ENODEV  no online VCPU
    -ENOMEM  memory shortage when allocating vgic internal data
    -EFAULT  Invalid guest ram access
    -EBUSY   One or more VCPUS are running
    =======  ========================================================

  KVM_DEV_ARM_VGIC_GRP_LEVEL_INFO
   Attributes:

    The attr field of kvm_device_attr encodes the following values::

      bits:     | 63      ....       32 | 31   ....    10 | 9  ....  0 |
      values:   |         mpidr         |      info       |   vINTID   |

    The vINTID specifies which set of IRQs is reported on.

    The info field specifies which information userspace wants to get or set
    using this interface.  Currently we support the following info values:

      VGIC_LEVEL_INFO_LINE_LEVEL:
	Get/Set the input level of the IRQ line for a set of 32 contiguously
	numbered interrupts.

	vINTID must be a multiple of 32.

	kvm_device_attr.addr points to a __u32 value which will contain a
	bitmap where a set bit means the interrupt level is asserted.

	Bit[n] indicates the status for interrupt vINTID + n.

    SGIs and any interrupt with a higher ID than the number of interrupts
    supported, will be RAZ/WI.  LPIs are always edge-triggered and are
    therefore not supported by this interface.

    PPIs are reported per VCPU as specified in the mpidr field, and SPIs are
    reported with the same value regardless of the mpidr specified.

    The mpidr field encodes the CPU ID based on the affinity information in the
    architecture defined MPIDR, and the field is encoded as follows::

      | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 |
      |    Aff3    |    Aff2    |    Aff1    |    Aff0    |

  Errors:

    =======  =============================================
    -EINVAL  vINTID is not multiple of 32 or info field is
	     not VGIC_LEVEL_INFO_LINE_LEVEL
    =======  =============================================


code:
.. SPDX-License-Identifier: GPL-2.0

==================================================
ARM Virtual Generic Interrupt Controller v2 (VGIC)
==================================================

Device types supported:

  - KVM_DEV_TYPE_ARM_VGIC_V2     ARM Generic Interrupt Controller v2.0

Only one VGIC instance may be instantiated through either this API or the
legacy KVM_CREATE_IRQCHIP API.  The created VGIC will act as the VM interrupt
controller, requiring emulated user-space devices to inject interrupts to the
VGIC instead of directly to CPUs.

GICv3 implementations with hardware compatibility support allow creating a
guest GICv2 through this interface.  For information on creating a guest GICv3
device and guest ITS devices, see arm-vgic-v3.txt.  It is not possible to
create both a GICv3 and GICv2 device on the same VM.

Groups:
  KVM_DEV_ARM_VGIC_GRP_ADDR
   Attributes:

    KVM_VGIC_V2_ADDR_TYPE_DIST (rw, 64-bit)
      Base address in the guest physical address space of the GIC distributor
      register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2.
      This address needs to be 4K aligned and the region covers 4 KByte.

    KVM_VGIC_V2_ADDR_TYPE_CPU (rw, 64-bit)
      Base address in the guest physical address space of the GIC virtual cpu
      interface register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2.
      This address needs to be 4K aligned and the region covers 4 KByte.

  Errors:

    =======  =============================================================
    -E2BIG   Address outside of addressable IPA range
    -EINVAL  Incorrectly aligned address
    -EEXIST  Address already configured
    -ENXIO   The group or attribute is unknown/unsupported for this device
             or hardware support is missing.
    -EFAULT  Invalid user pointer for attr->addr.
    =======  =============================================================

  KVM_DEV_ARM_VGIC_GRP_DIST_REGS
   Attributes:

    The attr field of kvm_device_attr encodes two values::

      bits:     | 63   ....  40 | 39 ..  32  |  31   ....    0 |
      values:   |    reserved   | vcpu_index |      offset     |

    All distributor regs are (rw, 32-bit)

    The offset is relative to the "Distributor base address" as defined in the
    GICv2 specs.  Getting or setting such a register has the same effect as
    reading or writing the register on the actual hardware from the cpu whose
    index is specified with the vcpu_index field.  Note that most distributor
    fields are not banked, but return the same value regardless of the
    vcpu_index used to access the register.

    GICD_IIDR.Revision is updated when the KVM implementation of an emulated
    GICv2 is changed in a way directly observable by the guest or userspace.
    Userspace should read GICD_IIDR from KVM and write back the read value to
    confirm its expected behavior is aligned with the KVM implementation.
    Userspace should set GICD_IIDR before setting any other registers (both
    KVM_DEV_ARM_VGIC_GRP_DIST_REGS and KVM_DEV_ARM_VGIC_GRP_CPU_REGS) to ensure
    the expected behavior. Unless GICD_IIDR has been set from userspace, writes
    to the interrupt group registers (GICD_IGROUPR) are ignored.

  Errors:

    =======  =====================================================
    -ENXIO   Getting or setting this register is not yet supported
    -EBUSY   One or more VCPUs are running
    -EINVAL  Invalid vcpu_index supplied
    =======  =====================================================

  KVM_DEV_ARM_VGIC_GRP_CPU_REGS
   Attributes:

    The attr field of kvm_device_attr encodes two values::

      bits:     | 63   ....  40 | 39 ..  32  |  31   ....    0 |
      values:   |    reserved   | vcpu_index |      offset     |

    All CPU interface regs are (rw, 32-bit)

    The offset specifies the offset from the "CPU interface base address" as
    defined in the GICv2 specs.  Getting or setting such a register has the
    same effect as reading or writing the register on the actual hardware.

    The Active Priorities Registers APRn are implementation defined, so we set a
    fixed format for our implementation that fits with the model of a "GICv2
    implementation without the security extensions" which we present to the
    guest.  This interface always exposes four register APR[0-3] describing the
    maximum possible 128 preemption levels.  The semantics of the register
    indicate if any interrupts in a given preemption level are in the active
    state by setting the corresponding bit.

    Thus, preemption level X has one or more active interrupts if and only if:

      APRn[X mod 32] == 0b1,  where n = X / 32

    Bits for undefined preemption levels are RAZ/WI.

    Note that this differs from a CPU's view of the APRs on hardware in which
    a GIC without the security extensions expose group 0 and group 1 active
    priorities in separate register groups, whereas we show a combined view
    similar to GICv2's GICH_APR.

    For historical reasons and to provide ABI compatibility with userspace we
    export the GICC_PMR register in the format of the GICH_VMCR.VMPriMask
    field in the lower 5 bits of a word, meaning that userspace must always
    use the lower 5 bits to communicate with the KVM device and must shift the
    value left by 3 places to obtain the actual priority mask level.

  Errors:

    =======  =====================================================
    -ENXIO   Getting or setting this register is not yet supported
    -EBUSY   One or more VCPUs are running
    -EINVAL  Invalid vcpu_index supplied
    =======  =====================================================

  KVM_DEV_ARM_VGIC_GRP_NR_IRQS
   Attributes:

    A value describing the number of interrupts (SGI, PPI and SPI) for
    this GIC instance, ranging from 64 to 1024, in increments of 32.

  Errors:

    =======  =============================================================
    -EINVAL  Value set is out of the expected range
    -EBUSY   Value has already be set, or GIC has already been initialized
             with default values.
    =======  =============================================================

  KVM_DEV_ARM_VGIC_GRP_CTRL
   Attributes:

    KVM_DEV_ARM_VGIC_CTRL_INIT
      request the initialization of the VGIC or ITS, no additional parameter
      in kvm_device_attr.addr.

  Errors:

    =======  =========================================================
    -ENXIO   VGIC not properly configured as required prior to calling
             this attribute
    -ENODEV  no online VCPU
    -ENOMEM  memory shortage when allocating vgic internal data
    =======  =========================================================


code:
.. SPDX-License-Identifier: GPL-2.0

=======
Devices
=======

.. toctree::
   :maxdepth: 2

   arm-vgic-its
   arm-vgic
   arm-vgic-v3
   mpic
   s390_flic
   vcpu
   vfio
   vm
   xics
   xive


code:
.. SPDX-License-Identifier: GPL-2.0

=========================
MPIC interrupt controller
=========================

Device types supported:

  - KVM_DEV_TYPE_FSL_MPIC_20     Freescale MPIC v2.0
  - KVM_DEV_TYPE_FSL_MPIC_42     Freescale MPIC v4.2

Only one MPIC instance, of any type, may be instantiated.  The created
MPIC will act as the system interrupt controller, connecting to each
vcpu's interrupt inputs.

Groups:
  KVM_DEV_MPIC_GRP_MISC
   Attributes:

    KVM_DEV_MPIC_BASE_ADDR (rw, 64-bit)
      Base address of the 256 KiB MPIC register space.  Must be
      naturally aligned.  A value of zero disables the mapping.
      Reset value is zero.

  KVM_DEV_MPIC_GRP_REGISTER (rw, 32-bit)
    Access an MPIC register, as if the access were made from the guest.
    "attr" is the byte offset into the MPIC register space.  Accesses
    must be 4-byte aligned.

    MSIs may be signaled by using this attribute group to write
    to the relevant MSIIR.

  KVM_DEV_MPIC_GRP_IRQ_ACTIVE (rw, 32-bit)
    IRQ input line for each standard openpic source.  0 is inactive and 1
    is active, regardless of interrupt sense.

    For edge-triggered interrupts:  Writing 1 is considered an activating
    edge, and writing 0 is ignored.  Reading returns 1 if a previously
    signaled edge has not been acknowledged, and 0 otherwise.

    "attr" is the IRQ number.  IRQ numbers for standard sources are the
    byte offset of the relevant IVPR from EIVPR0, divided by 32.

IRQ Routing:

  The MPIC emulation supports IRQ routing. Only a single MPIC device can
  be instantiated. Once that device has been created, it's available as
  irqchip id 0.

  This irqchip 0 has 256 interrupt pins, which expose the interrupts in
  the main array of interrupt sources (a.k.a. "SRC" interrupts).

  The numbering is the same as the MPIC device tree binding -- based on
  the register offset from the beginning of the sources array, without
  regard to any subdivisions in chip documentation such as "internal"
  or "external" interrupts.

  Access to non-SRC interrupts is not implemented through IRQ routing mechanisms.


code:
.. SPDX-License-Identifier: GPL-2.0

====================================
FLIC (floating interrupt controller)
====================================

FLIC handles floating (non per-cpu) interrupts, i.e. I/O, service and some
machine check interruptions. All interrupts are stored in a per-vm list of
pending interrupts. FLIC performs operations on this list.

Only one FLIC instance may be instantiated.

FLIC provides support to
- add interrupts (KVM_DEV_FLIC_ENQUEUE)
- inspect currently pending interrupts (KVM_FLIC_GET_ALL_IRQS)
- purge all pending floating interrupts (KVM_DEV_FLIC_CLEAR_IRQS)
- purge one pending floating I/O interrupt (KVM_DEV_FLIC_CLEAR_IO_IRQ)
- enable/disable for the guest transparent async page faults
- register and modify adapter interrupt sources (KVM_DEV_FLIC_ADAPTER_*)
- modify AIS (adapter-interruption-suppression) mode state (KVM_DEV_FLIC_AISM)
- inject adapter interrupts on a specified adapter (KVM_DEV_FLIC_AIRQ_INJECT)
- get/set all AIS mode states (KVM_DEV_FLIC_AISM_ALL)

Groups:
  KVM_DEV_FLIC_ENQUEUE
    Passes a buffer and length into the kernel which are then injected into
    the list of pending interrupts.
    attr->addr contains the pointer to the buffer and attr->attr contains
    the length of the buffer.
    The format of the data structure kvm_s390_irq as it is copied from userspace
    is defined in usr/include/linux/kvm.h.

  KVM_DEV_FLIC_GET_ALL_IRQS
    Copies all floating interrupts into a buffer provided by userspace.
    When the buffer is too small it returns -ENOMEM, which is the indication
    for userspace to try again with a bigger buffer.

    -ENOBUFS is returned when the allocation of a kernelspace buffer has
    failed.

    -EFAULT is returned when copying data to userspace failed.
    All interrupts remain pending, i.e. are not deleted from the list of
    currently pending interrupts.
    attr->addr contains the userspace address of the buffer into which all
    interrupt data will be copied.
    attr->attr contains the size of the buffer in bytes.

  KVM_DEV_FLIC_CLEAR_IRQS
    Simply deletes all elements from the list of currently pending floating
    interrupts.  No interrupts are injected into the guest.

  KVM_DEV_FLIC_CLEAR_IO_IRQ
    Deletes one (if any) I/O interrupt for a subchannel identified by the
    subsystem identification word passed via the buffer specified by
    attr->addr (address) and attr->attr (length).

  KVM_DEV_FLIC_APF_ENABLE
    Enables async page faults for the guest. So in case of a major page fault
    the host is allowed to handle this async and continues the guest.

  KVM_DEV_FLIC_APF_DISABLE_WAIT
    Disables async page faults for the guest and waits until already pending
    async page faults are done. This is necessary to trigger a completion interrupt
    for every init interrupt before migrating the interrupt list.

  KVM_DEV_FLIC_ADAPTER_REGISTER
    Register an I/O adapter interrupt source. Takes a kvm_s390_io_adapter
    describing the adapter to register::

	struct kvm_s390_io_adapter {
		__u32 id;
		__u8 isc;
		__u8 maskable;
		__u8 swap;
		__u8 flags;
	};

   id contains the unique id for the adapter, isc the I/O interruption subclass
   to use, maskable whether this adapter may be masked (interrupts turned off),
   swap whether the indicators need to be byte swapped, and flags contains
   further characteristics of the adapter.

   Currently defined values for 'flags' are:

   - KVM_S390_ADAPTER_SUPPRESSIBLE: adapter is subject to AIS
     (adapter-interrupt-suppression) facility. This flag only has an effect if
     the AIS capability is enabled.

   Unknown flag values are ignored.

  KVM_DEV_FLIC_ADAPTER_MODIFY
    Modifies attributes of an existing I/O adapter interrupt source. Takes
    a kvm_s390_io_adapter_req specifying the adapter and the operation::

	struct kvm_s390_io_adapter_req {
		__u32 id;
		__u8 type;
		__u8 mask;
		__u16 pad0;
		__u64 addr;
	};

    id specifies the adapter and type the operation. The supported operations
    are:

    KVM_S390_IO_ADAPTER_MASK
      mask or unmask the adapter, as specified in mask

    KVM_S390_IO_ADAPTER_MAP
      This is now a no-op. The mapping is purely done by the irq route.
    KVM_S390_IO_ADAPTER_UNMAP
      This is now a no-op. The mapping is purely done by the irq route.

  KVM_DEV_FLIC_AISM
    modify the adapter-interruption-suppression mode for a given isc if the
    AIS capability is enabled. Takes a kvm_s390_ais_req describing::

	struct kvm_s390_ais_req {
		__u8 isc;
		__u16 mode;
	};

    isc contains the target I/O interruption subclass, mode the target
    adapter-interruption-suppression mode. The following modes are
    currently supported:

    - KVM_S390_AIS_MODE_ALL: ALL-Interruptions Mode, i.e. airq injection
      is always allowed;
    - KVM_S390_AIS_MODE_SINGLE: SINGLE-Interruption Mode, i.e. airq
      injection is only allowed once and the following adapter interrupts
      will be suppressed until the mode is set again to ALL-Interruptions
      or SINGLE-Interruption mode.

  KVM_DEV_FLIC_AIRQ_INJECT
    Inject adapter interrupts on a specified adapter.
    attr->attr contains the unique id for the adapter, which allows for
    adapter-specific checks and actions.
    For adapters subject to AIS, handle the airq injection suppression for
    an isc according to the adapter-interruption-suppression mode on condition
    that the AIS capability is enabled.

  KVM_DEV_FLIC_AISM_ALL
    Gets or sets the adapter-interruption-suppression mode for all ISCs. Takes
    a kvm_s390_ais_all describing::

	struct kvm_s390_ais_all {
	       __u8 simm; /* Single-Interruption-Mode mask */
	       __u8 nimm; /* No-Interruption-Mode mask *
	};

    simm contains Single-Interruption-Mode mask for all ISCs, nimm contains
    No-Interruption-Mode mask for all ISCs. Each bit in simm and nimm corresponds
    to an ISC (MSB0 bit 0 to ISC 0 and so on). The combination of simm bit and
    nimm bit presents AIS mode for a ISC.

    KVM_DEV_FLIC_AISM_ALL is indicated by KVM_CAP_S390_AIS_MIGRATION.

Note: The KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR device ioctls executed on
FLIC with an unknown group or attribute gives the error code EINVAL (instead of
ENXIO, as specified in the API documentation). It is not possible to conclude
that a FLIC operation is unavailable based on the error code resulting from a
usage attempt.

.. note:: The KVM_DEV_FLIC_CLEAR_IO_IRQ ioctl will return EINVAL in case a
	  zero schid is specified.


code:
.. SPDX-License-Identifier: GPL-2.0

======================
Generic vcpu interface
======================

The virtual cpu "device" also accepts the ioctls KVM_SET_DEVICE_ATTR,
KVM_GET_DEVICE_ATTR, and KVM_HAS_DEVICE_ATTR. The interface uses the same struct
kvm_device_attr as other devices, but targets VCPU-wide settings and controls.

The groups and attributes per virtual cpu, if any, are architecture specific.

1. GROUP: KVM_ARM_VCPU_PMU_V3_CTRL
==================================

:Architectures: ARM64

1.1. ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_IRQ
---------------------------------------

:Parameters: in kvm_device_attr.addr the address for PMU overflow interrupt is a
	     pointer to an int

Returns:

	 =======  ========================================================
	 -EBUSY   The PMU overflow interrupt is already set
	 -EFAULT  Error reading interrupt number
	 -ENXIO   PMUv3 not supported or the overflow interrupt not set
		  when attempting to get it
	 -ENODEV  KVM_ARM_VCPU_PMU_V3 feature missing from VCPU
	 -EINVAL  Invalid PMU overflow interrupt number supplied or
		  trying to set the IRQ number without using an in-kernel
		  irqchip.
	 =======  ========================================================

A value describing the PMUv3 (Performance Monitor Unit v3) overflow interrupt
number for this vcpu. This interrupt could be a PPI or SPI, but the interrupt
type must be same for each vcpu. As a PPI, the interrupt number is the same for
all vcpus, while as an SPI it must be a separate number per vcpu.

1.2 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_INIT
---------------------------------------

:Parameters: no additional parameter in kvm_device_attr.addr

Returns:

	 =======  ======================================================
	 -EEXIST  Interrupt number already used
	 -ENODEV  PMUv3 not supported or GIC not initialized
	 -ENXIO   PMUv3 not supported, missing VCPU feature or interrupt
		  number not set
	 -EBUSY   PMUv3 already initialized
	 =======  ======================================================

Request the initialization of the PMUv3.  If using the PMUv3 with an in-kernel
virtual GIC implementation, this must be done after initializing the in-kernel
irqchip.

1.3 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_FILTER
-----------------------------------------

:Parameters: in kvm_device_attr.addr the address for a PMU event filter is a
             pointer to a struct kvm_pmu_event_filter

:Returns:

	 =======  ======================================================
	 -ENODEV  PMUv3 not supported or GIC not initialized
	 -ENXIO   PMUv3 not properly configured or in-kernel irqchip not
	 	  configured as required prior to calling this attribute
	 -EBUSY   PMUv3 already initialized or a VCPU has already run
	 -EINVAL  Invalid filter range
	 =======  ======================================================

Request the installation of a PMU event filter described as follows::

    struct kvm_pmu_event_filter {
	    __u16	base_event;
	    __u16	nevents;

    #define KVM_PMU_EVENT_ALLOW	0
    #define KVM_PMU_EVENT_DENY	1

	    __u8	action;
	    __u8	pad[3];
    };

A filter range is defined as the range [@base_event, @base_event + @nevents),
together with an @action (KVM_PMU_EVENT_ALLOW or KVM_PMU_EVENT_DENY). The
first registered range defines the global policy (global ALLOW if the first
@action is DENY, global DENY if the first @action is ALLOW). Multiple ranges
can be programmed, and must fit within the event space defined by the PMU
architecture (10 bits on ARMv8.0, 16 bits from ARMv8.1 onwards).

Note: "Cancelling" a filter by registering the opposite action for the same
range doesn't change the default action. For example, installing an ALLOW
filter for event range [0:10) as the first filter and then applying a DENY
action for the same range will leave the whole range as disabled.

Restrictions: Event 0 (SW_INCR) is never filtered, as it doesn't count a
hardware event. Filtering event 0x1E (CHAIN) has no effect either, as it
isn't strictly speaking an event. Filtering the cycle counter is possible
using event 0x11 (CPU_CYCLES).

1.4 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_SET_PMU
------------------------------------------

:Parameters: in kvm_device_attr.addr the address to an int representing the PMU
             identifier.

:Returns:

	 =======  ====================================================
	 -EBUSY   PMUv3 already initialized, a VCPU has already run or
                  an event filter has already been set
	 -EFAULT  Error accessing the PMU identifier
	 -ENXIO   PMU not found
	 -ENODEV  PMUv3 not supported or GIC not initialized
	 -ENOMEM  Could not allocate memory
	 =======  ====================================================

Request that the VCPU uses the specified hardware PMU when creating guest events
for the purpose of PMU emulation. The PMU identifier can be read from the "type"
file for the desired PMU instance under /sys/devices (or, equivalent,
/sys/bus/even_source). This attribute is particularly useful on heterogeneous
systems where there are at least two CPU PMUs on the system. The PMU that is set
for one VCPU will be used by all the other VCPUs. It isn't possible to set a PMU
if a PMU event filter is already present.

Note that KVM will not make any attempts to run the VCPU on the physical CPUs
associated with the PMU specified by this attribute. This is entirely left to
userspace. However, attempting to run the VCPU on a physical CPU not supported
by the PMU will fail and KVM_RUN will return with
exit_reason = KVM_EXIT_FAIL_ENTRY and populate the fail_entry struct by setting
hardare_entry_failure_reason field to KVM_EXIT_FAIL_ENTRY_CPU_UNSUPPORTED and
the cpu field to the processor id.

2. GROUP: KVM_ARM_VCPU_TIMER_CTRL
=================================

:Architectures: ARM64

2.1. ATTRIBUTES: KVM_ARM_VCPU_TIMER_IRQ_VTIMER, KVM_ARM_VCPU_TIMER_IRQ_PTIMER
-----------------------------------------------------------------------------

:Parameters: in kvm_device_attr.addr the address for the timer interrupt is a
	     pointer to an int

Returns:

	 =======  =================================
	 -EINVAL  Invalid timer interrupt number
	 -EBUSY   One or more VCPUs has already run
	 =======  =================================

A value describing the architected timer interrupt number when connected to an
in-kernel virtual GIC.  These must be a PPI (16 <= intid < 32).  Setting the
attribute overrides the default values (see below).

=============================  ==========================================
KVM_ARM_VCPU_TIMER_IRQ_VTIMER  The EL1 virtual timer intid (default: 27)
KVM_ARM_VCPU_TIMER_IRQ_PTIMER  The EL1 physical timer intid (default: 30)
=============================  ==========================================

Setting the same PPI for different timers will prevent the VCPUs from running.
Setting the interrupt number on a VCPU configures all VCPUs created at that
time to use the number provided for a given timer, overwriting any previously
configured values on other VCPUs.  Userspace should configure the interrupt
numbers on at least one VCPU after creating all VCPUs and before running any
VCPUs.

.. _kvm_arm_vcpu_pvtime_ctrl:

3. GROUP: KVM_ARM_VCPU_PVTIME_CTRL
==================================

:Architectures: ARM64

3.1 ATTRIBUTE: KVM_ARM_VCPU_PVTIME_IPA
--------------------------------------

:Parameters: 64-bit base address

Returns:

	 =======  ======================================
	 -ENXIO   Stolen time not implemented
	 -EEXIST  Base address already set for this VCPU
	 -EINVAL  Base address not 64 byte aligned
	 =======  ======================================

Specifies the base address of the stolen time structure for this VCPU. The
base address must be 64 byte aligned and exist within a valid guest memory
region. See Documentation/virt/kvm/arm/pvtime.rst for more information
including the layout of the stolen time structure.

4. GROUP: KVM_VCPU_TSC_CTRL
===========================

:Architectures: x86

4.1 ATTRIBUTE: KVM_VCPU_TSC_OFFSET

:Parameters: 64-bit unsigned TSC offset

Returns:

	 ======= ======================================
	 -EFAULT Error reading/writing the provided
		 parameter address.
	 -ENXIO  Attribute not supported
	 ======= ======================================

Specifies the guest's TSC offset relative to the host's TSC. The guest's
TSC is then derived by the following equation:

  guest_tsc = host_tsc + KVM_VCPU_TSC_OFFSET

This attribute is useful to adjust the guest's TSC on live migration,
so that the TSC counts the time during which the VM was paused. The
following describes a possible algorithm to use for this purpose.

From the source VMM process:

1. Invoke the KVM_GET_CLOCK ioctl to record the host TSC (tsc_src),
   kvmclock nanoseconds (guest_src), and host CLOCK_REALTIME nanoseconds
   (host_src).

2. Read the KVM_VCPU_TSC_OFFSET attribute for every vCPU to record the
   guest TSC offset (ofs_src[i]).

3. Invoke the KVM_GET_TSC_KHZ ioctl to record the frequency of the
   guest's TSC (freq).

From the destination VMM process:

4. Invoke the KVM_SET_CLOCK ioctl, providing the source nanoseconds from
   kvmclock (guest_src) and CLOCK_REALTIME (host_src) in their respective
   fields.  Ensure that the KVM_CLOCK_REALTIME flag is set in the provided
   structure.

   KVM will advance the VM's kvmclock to account for elapsed time since
   recording the clock values.  Note that this will cause problems in
   the guest (e.g., timeouts) unless CLOCK_REALTIME is synchronized
   between the source and destination, and a reasonably short time passes
   between the source pausing the VMs and the destination executing
   steps 4-7.

5. Invoke the KVM_GET_CLOCK ioctl to record the host TSC (tsc_dest) and
   kvmclock nanoseconds (guest_dest).

6. Adjust the guest TSC offsets for every vCPU to account for (1) time
   elapsed since recording state and (2) difference in TSCs between the
   source and destination machine:

   ofs_dst[i] = ofs_src[i] -
     (guest_src - guest_dest) * freq +
     (tsc_src - tsc_dest)

   ("ofs[i] + tsc - guest * freq" is the guest TSC value corresponding to
   a time of 0 in kvmclock.  The above formula ensures that it is the
   same on the destination as it was on the source).

7. Write the KVM_VCPU_TSC_OFFSET attribute for every vCPU with the
   respective value derived in the previous step.


code:
.. SPDX-License-Identifier: GPL-2.0

===================
VFIO virtual device
===================

Device types supported:

  - KVM_DEV_TYPE_VFIO

Only one VFIO instance may be created per VM.  The created device
tracks VFIO groups in use by the VM and features of those groups
important to the correctness and acceleration of the VM.  As groups
are enabled and disabled for use by the VM, KVM should be updated
about their presence.  When registered with KVM, a reference to the
VFIO-group is held by KVM.

Groups:
  KVM_DEV_VFIO_GROUP

KVM_DEV_VFIO_GROUP attributes:
  KVM_DEV_VFIO_GROUP_ADD: Add a VFIO group to VFIO-KVM device tracking
	kvm_device_attr.addr points to an int32_t file descriptor
	for the VFIO group.
  KVM_DEV_VFIO_GROUP_DEL: Remove a VFIO group from VFIO-KVM device tracking
	kvm_device_attr.addr points to an int32_t file descriptor
	for the VFIO group.
  KVM_DEV_VFIO_GROUP_SET_SPAPR_TCE: attaches a guest visible TCE table
	allocated by sPAPR KVM.
	kvm_device_attr.addr points to a struct::

		struct kvm_vfio_spapr_tce {
			__s32	groupfd;
			__s32	tablefd;
		};

	where:

	- @groupfd is a file descriptor for a VFIO group;
	- @tablefd is a file descriptor for a TCE table allocated via
	  KVM_CREATE_SPAPR_TCE.


code:
.. SPDX-License-Identifier: GPL-2.0

====================
Generic vm interface
====================

The virtual machine "device" also accepts the ioctls KVM_SET_DEVICE_ATTR,
KVM_GET_DEVICE_ATTR, and KVM_HAS_DEVICE_ATTR. The interface uses the same
struct kvm_device_attr as other devices, but targets VM-wide settings
and controls.

The groups and attributes per virtual machine, if any, are architecture
specific.

1. GROUP: KVM_S390_VM_MEM_CTRL
==============================

:Architectures: s390

1.1. ATTRIBUTE: KVM_S390_VM_MEM_ENABLE_CMMA
-------------------------------------------

:Parameters: none
:Returns: -EBUSY if a vcpu is already defined, otherwise 0

Enables Collaborative Memory Management Assist (CMMA) for the virtual machine.

1.2. ATTRIBUTE: KVM_S390_VM_MEM_CLR_CMMA
----------------------------------------

:Parameters: none
:Returns: -EINVAL if CMMA was not enabled;
	  0 otherwise

Clear the CMMA status for all guest pages, so any pages the guest marked
as unused are again used any may not be reclaimed by the host.

1.3. ATTRIBUTE KVM_S390_VM_MEM_LIMIT_SIZE
-----------------------------------------

:Parameters: in attr->addr the address for the new limit of guest memory
:Returns: -EFAULT if the given address is not accessible;
	  -EINVAL if the virtual machine is of type UCONTROL;
	  -E2BIG if the given guest memory is to big for that machine;
	  -EBUSY if a vcpu is already defined;
	  -ENOMEM if not enough memory is available for a new shadow guest mapping;
	  0 otherwise.

Allows userspace to query the actual limit and set a new limit for
the maximum guest memory size. The limit will be rounded up to
2048 MB, 4096 GB, 8192 TB respectively, as this limit is governed by
the number of page table levels. In the case that there is no limit we will set
the limit to KVM_S390_NO_MEM_LIMIT (U64_MAX).

2. GROUP: KVM_S390_VM_CPU_MODEL
===============================

:Architectures: s390

2.1. ATTRIBUTE: KVM_S390_VM_CPU_MACHINE (r/o)
---------------------------------------------

Allows user space to retrieve machine and kvm specific cpu related information::

  struct kvm_s390_vm_cpu_machine {
       __u64 cpuid;           # CPUID of host
       __u32 ibc;             # IBC level range offered by host
       __u8  pad[4];
       __u64 fac_mask[256];   # set of cpu facilities enabled by KVM
       __u64 fac_list[256];   # set of cpu facilities offered by host
  }

:Parameters: address of buffer to store the machine related cpu data
	     of type struct kvm_s390_vm_cpu_machine*
:Returns:   -EFAULT if the given address is not accessible from kernel space;
	    -ENOMEM if not enough memory is available to process the ioctl;
	    0 in case of success.

2.2. ATTRIBUTE: KVM_S390_VM_CPU_PROCESSOR (r/w)
===============================================

Allows user space to retrieve or request to change cpu related information for a vcpu::

  struct kvm_s390_vm_cpu_processor {
       __u64 cpuid;           # CPUID currently (to be) used by this vcpu
       __u16 ibc;             # IBC level currently (to be) used by this vcpu
       __u8  pad[6];
       __u64 fac_list[256];   # set of cpu facilities currently (to be) used
			      # by this vcpu
  }

KVM does not enforce or limit the cpu model data in any form. Take the information
retrieved by means of KVM_S390_VM_CPU_MACHINE as hint for reasonable configuration
setups. Instruction interceptions triggered by additionally set facility bits that
are not handled by KVM need to by imlemented in the VM driver code.

:Parameters: address of buffer to store/set the processor related cpu
	     data of type struct kvm_s390_vm_cpu_processor*.
:Returns:  -EBUSY in case 1 or more vcpus are already activated (only in write case);
	   -EFAULT if the given address is not accessible from kernel space;
	   -ENOMEM if not enough memory is available to process the ioctl;
	   0 in case of success.

.. _KVM_S390_VM_CPU_MACHINE_FEAT:

2.3. ATTRIBUTE: KVM_S390_VM_CPU_MACHINE_FEAT (r/o)
--------------------------------------------------

Allows user space to retrieve available cpu features. A feature is available if
provided by the hardware and supported by kvm. In theory, cpu features could
even be completely emulated by kvm.

::

  struct kvm_s390_vm_cpu_feat {
	__u64 feat[16]; # Bitmap (1 = feature available), MSB 0 bit numbering
  };

:Parameters: address of a buffer to load the feature list from.
:Returns:  -EFAULT if the given address is not accessible from kernel space;
	   0 in case of success.

2.4. ATTRIBUTE: KVM_S390_VM_CPU_PROCESSOR_FEAT (r/w)
----------------------------------------------------

Allows user space to retrieve or change enabled cpu features for all VCPUs of a
VM. Features that are not available cannot be enabled.

See :ref:`KVM_S390_VM_CPU_MACHINE_FEAT` for
a description of the parameter struct.

:Parameters: address of a buffer to store/load the feature list from.
:Returns:   -EFAULT if the given address is not accessible from kernel space;
	    -EINVAL if a cpu feature that is not available is to be enabled;
	    -EBUSY if at least one VCPU has already been defined;
	    0 in case of success.

.. _KVM_S390_VM_CPU_MACHINE_SUBFUNC:

2.5. ATTRIBUTE: KVM_S390_VM_CPU_MACHINE_SUBFUNC (r/o)
-----------------------------------------------------

Allows user space to retrieve available cpu subfunctions without any filtering
done by a set IBC. These subfunctions are indicated to the guest VCPU via
query or "test bit" subfunctions and used e.g. by cpacf functions, plo and ptff.

A subfunction block is only valid if KVM_S390_VM_CPU_MACHINE contains the
STFL(E) bit introducing the affected instruction. If the affected instruction
indicates subfunctions via a "query subfunction", the response block is
contained in the returned struct. If the affected instruction
indicates subfunctions via a "test bit" mechanism, the subfunction codes are
contained in the returned struct in MSB 0 bit numbering.

::

  struct kvm_s390_vm_cpu_subfunc {
       u8 plo[32];           # always valid (ESA/390 feature)
       u8 ptff[16];          # valid with TOD-clock steering
       u8 kmac[16];          # valid with Message-Security-Assist
       u8 kmc[16];           # valid with Message-Security-Assist
       u8 km[16];            # valid with Message-Security-Assist
       u8 kimd[16];          # valid with Message-Security-Assist
       u8 klmd[16];          # valid with Message-Security-Assist
       u8 pckmo[16];         # valid with Message-Security-Assist-Extension 3
       u8 kmctr[16];         # valid with Message-Security-Assist-Extension 4
       u8 kmf[16];           # valid with Message-Security-Assist-Extension 4
       u8 kmo[16];           # valid with Message-Security-Assist-Extension 4
       u8 pcc[16];           # valid with Message-Security-Assist-Extension 4
       u8 ppno[16];          # valid with Message-Security-Assist-Extension 5
       u8 kma[16];           # valid with Message-Security-Assist-Extension 8
       u8 kdsa[16];          # valid with Message-Security-Assist-Extension 9
       u8 reserved[1792];    # reserved for future instructions
  };

:Parameters: address of a buffer to load the subfunction blocks from.
:Returns:   -EFAULT if the given address is not accessible from kernel space;
	    0 in case of success.

2.6. ATTRIBUTE: KVM_S390_VM_CPU_PROCESSOR_SUBFUNC (r/w)
-------------------------------------------------------

Allows user space to retrieve or change cpu subfunctions to be indicated for
all VCPUs of a VM. This attribute will only be available if kernel and
hardware support are in place.

The kernel uses the configured subfunction blocks for indication to
the guest. A subfunction block will only be used if the associated STFL(E) bit
has not been disabled by user space (so the instruction to be queried is
actually available for the guest).

As long as no data has been written, a read will fail. The IBC will be used
to determine available subfunctions in this case, this will guarantee backward
compatibility.

See :ref:`KVM_S390_VM_CPU_MACHINE_SUBFUNC` for a
description of the parameter struct.

:Parameters: address of a buffer to store/load the subfunction blocks from.
:Returns:   -EFAULT if the given address is not accessible from kernel space;
	    -EINVAL when reading, if there was no write yet;
	    -EBUSY if at least one VCPU has already been defined;
	    0 in case of success.

3. GROUP: KVM_S390_VM_TOD
=========================

:Architectures: s390

3.1. ATTRIBUTE: KVM_S390_VM_TOD_HIGH
------------------------------------

Allows user space to set/get the TOD clock extension (u8) (superseded by
KVM_S390_VM_TOD_EXT).

:Parameters: address of a buffer in user space to store the data (u8) to
:Returns:   -EFAULT if the given address is not accessible from kernel space;
	    -EINVAL if setting the TOD clock extension to != 0 is not supported
	    -EOPNOTSUPP for a PV guest (TOD managed by the ultravisor)

3.2. ATTRIBUTE: KVM_S390_VM_TOD_LOW
-----------------------------------

Allows user space to set/get bits 0-63 of the TOD clock register as defined in
the POP (u64).

:Parameters: address of a buffer in user space to store the data (u64) to
:Returns:    -EFAULT if the given address is not accessible from kernel space
	     -EOPNOTSUPP for a PV guest (TOD managed by the ultravisor)

3.3. ATTRIBUTE: KVM_S390_VM_TOD_EXT
-----------------------------------

Allows user space to set/get bits 0-63 of the TOD clock register as defined in
the POP (u64). If the guest CPU model supports the TOD clock extension (u8), it
also allows user space to get/set it. If the guest CPU model does not support
it, it is stored as 0 and not allowed to be set to a value != 0.

:Parameters: address of a buffer in user space to store the data
	     (kvm_s390_vm_tod_clock) to
:Returns:   -EFAULT if the given address is not accessible from kernel space;
	    -EINVAL if setting the TOD clock extension to != 0 is not supported
	    -EOPNOTSUPP for a PV guest (TOD managed by the ultravisor)

4. GROUP: KVM_S390_VM_CRYPTO
============================

:Architectures: s390

4.1. ATTRIBUTE: KVM_S390_VM_CRYPTO_ENABLE_AES_KW (w/o)
------------------------------------------------------

Allows user space to enable aes key wrapping, including generating a new
wrapping key.

:Parameters: none
:Returns:    0

4.2. ATTRIBUTE: KVM_S390_VM_CRYPTO_ENABLE_DEA_KW (w/o)
------------------------------------------------------

Allows user space to enable dea key wrapping, including generating a new
wrapping key.

:Parameters: none
:Returns:    0

4.3. ATTRIBUTE: KVM_S390_VM_CRYPTO_DISABLE_AES_KW (w/o)
-------------------------------------------------------

Allows user space to disable aes key wrapping, clearing the wrapping key.

:Parameters: none
:Returns:    0

4.4. ATTRIBUTE: KVM_S390_VM_CRYPTO_DISABLE_DEA_KW (w/o)
-------------------------------------------------------

Allows user space to disable dea key wrapping, clearing the wrapping key.

:Parameters: none
:Returns:    0

5. GROUP: KVM_S390_VM_MIGRATION
===============================

:Architectures: s390

5.1. ATTRIBUTE: KVM_S390_VM_MIGRATION_STOP (w/o)
------------------------------------------------

Allows userspace to stop migration mode, needed for PGSTE migration.
Setting this attribute when migration mode is not active will have no
effects.

:Parameters: none
:Returns:    0

5.2. ATTRIBUTE: KVM_S390_VM_MIGRATION_START (w/o)
-------------------------------------------------

Allows userspace to start migration mode, needed for PGSTE migration.
Setting this attribute when migration mode is already active will have
no effects.

:Parameters: none
:Returns:   -ENOMEM if there is not enough free memory to start migration mode;
	    -EINVAL if the state of the VM is invalid (e.g. no memory defined);
	    0 in case of success.

5.3. ATTRIBUTE: KVM_S390_VM_MIGRATION_STATUS (r/o)
--------------------------------------------------

Allows userspace to query the status of migration mode.

:Parameters: address of a buffer in user space to store the data (u64) to;
	     the data itself is either 0 if migration mode is disabled or 1
	     if it is enabled
:Returns:   -EFAULT if the given address is not accessible from kernel space;
	    0 in case of success.


code:
.. SPDX-License-Identifier: GPL-2.0

=========================
XICS interrupt controller
=========================

Device type supported: KVM_DEV_TYPE_XICS

Groups:
  1. KVM_DEV_XICS_GRP_SOURCES
       Attributes:

         One per interrupt source, indexed by the source number.
  2. KVM_DEV_XICS_GRP_CTRL
       Attributes:

         2.1 KVM_DEV_XICS_NR_SERVERS (write only)

  The kvm_device_attr.addr points to a __u32 value which is the number of
  interrupt server numbers (ie, highest possible vcpu id plus one).

  Errors:

    =======  ==========================================
    -EINVAL  Value greater than KVM_MAX_VCPU_IDS.
    -EFAULT  Invalid user pointer for attr->addr.
    -EBUSY   A vcpu is already connected to the device.
    =======  ==========================================

This device emulates the XICS (eXternal Interrupt Controller
Specification) defined in PAPR.  The XICS has a set of interrupt
sources, each identified by a 20-bit source number, and a set of
Interrupt Control Presentation (ICP) entities, also called "servers",
each associated with a virtual CPU.

The ICP entities are created by enabling the KVM_CAP_IRQ_ARCH
capability for each vcpu, specifying KVM_CAP_IRQ_XICS in args[0] and
the interrupt server number (i.e. the vcpu number from the XICS's
point of view) in args[1] of the kvm_enable_cap struct.  Each ICP has
64 bits of state which can be read and written using the
KVM_GET_ONE_REG and KVM_SET_ONE_REG ioctls on the vcpu.  The 64 bit
state word has the following bitfields, starting at the
least-significant end of the word:

* Unused, 16 bits

* Pending interrupt priority, 8 bits
  Zero is the highest priority, 255 means no interrupt is pending.

* Pending IPI (inter-processor interrupt) priority, 8 bits
  Zero is the highest priority, 255 means no IPI is pending.

* Pending interrupt source number, 24 bits
  Zero means no interrupt pending, 2 means an IPI is pending

* Current processor priority, 8 bits
  Zero is the highest priority, meaning no interrupts can be
  delivered, and 255 is the lowest priority.

Each source has 64 bits of state that can be read and written using
the KVM_GET_DEVICE_ATTR and KVM_SET_DEVICE_ATTR ioctls, specifying the
KVM_DEV_XICS_GRP_SOURCES attribute group, with the attribute number being
the interrupt source number.  The 64 bit state word has the following
bitfields, starting from the least-significant end of the word:

* Destination (server number), 32 bits

  This specifies where the interrupt should be sent, and is the
  interrupt server number specified for the destination vcpu.

* Priority, 8 bits

  This is the priority specified for this interrupt source, where 0 is
  the highest priority and 255 is the lowest.  An interrupt with a
  priority of 255 will never be delivered.

* Level sensitive flag, 1 bit

  This bit is 1 for a level-sensitive interrupt source, or 0 for
  edge-sensitive (or MSI).

* Masked flag, 1 bit

  This bit is set to 1 if the interrupt is masked (cannot be delivered
  regardless of its priority), for example by the ibm,int-off RTAS
  call, or 0 if it is not masked.

* Pending flag, 1 bit

  This bit is 1 if the source has a pending interrupt, otherwise 0.

Only one XICS instance may be created per VM.


code:
.. SPDX-License-Identifier: GPL-2.0

===========================================================
POWER9 eXternal Interrupt Virtualization Engine (XIVE Gen1)
===========================================================

Device types supported:
  - KVM_DEV_TYPE_XIVE     POWER9 XIVE Interrupt Controller generation 1

This device acts as a VM interrupt controller. It provides the KVM
interface to configure the interrupt sources of a VM in the underlying
POWER9 XIVE interrupt controller.

Only one XIVE instance may be instantiated. A guest XIVE device
requires a POWER9 host and the guest OS should have support for the
XIVE native exploitation interrupt mode. If not, it should run using
the legacy interrupt mode, referred as XICS (POWER7/8).

* Device Mappings

  The KVM device exposes different MMIO ranges of the XIVE HW which
  are required for interrupt management. These are exposed to the
  guest in VMAs populated with a custom VM fault handler.

  1. Thread Interrupt Management Area (TIMA)

  Each thread has an associated Thread Interrupt Management context
  composed of a set of registers. These registers let the thread
  handle priority management and interrupt acknowledgment. The most
  important are :

      - Interrupt Pending Buffer     (IPB)
      - Current Processor Priority   (CPPR)
      - Notification Source Register (NSR)

  They are exposed to software in four different pages each proposing
  a view with a different privilege. The first page is for the
  physical thread context and the second for the hypervisor. Only the
  third (operating system) and the fourth (user level) are exposed the
  guest.

  2. Event State Buffer (ESB)

  Each source is associated with an Event State Buffer (ESB) with
  either a pair of even/odd pair of pages which provides commands to
  manage the source: to trigger, to EOI, to turn off the source for
  instance.

  3. Device pass-through

  When a device is passed-through into the guest, the source
  interrupts are from a different HW controller (PHB4) and the ESB
  pages exposed to the guest should accommadate this change.

  The passthru_irq helpers, kvmppc_xive_set_mapped() and
  kvmppc_xive_clr_mapped() are called when the device HW irqs are
  mapped into or unmapped from the guest IRQ number space. The KVM
  device extends these helpers to clear the ESB pages of the guest IRQ
  number being mapped and then lets the VM fault handler repopulate.
  The handler will insert the ESB page corresponding to the HW
  interrupt of the device being passed-through or the initial IPI ESB
  page if the device has being removed.

  The ESB remapping is fully transparent to the guest and the OS
  device driver. All handling is done within VFIO and the above
  helpers in KVM-PPC.

* Groups:

1. KVM_DEV_XIVE_GRP_CTRL
     Provides global controls on the device

  Attributes:
    1.1 KVM_DEV_XIVE_RESET (write only)
    Resets the interrupt controller configuration for sources and event
    queues. To be used by kexec and kdump.

    Errors: none

    1.2 KVM_DEV_XIVE_EQ_SYNC (write only)
    Sync all the sources and queues and mark the EQ pages dirty. This
    to make sure that a consistent memory state is captured when
    migrating the VM.

    Errors: none

    1.3 KVM_DEV_XIVE_NR_SERVERS (write only)
    The kvm_device_attr.addr points to a __u32 value which is the number of
    interrupt server numbers (ie, highest possible vcpu id plus one).

    Errors:

      =======  ==========================================
      -EINVAL  Value greater than KVM_MAX_VCPU_IDS.
      -EFAULT  Invalid user pointer for attr->addr.
      -EBUSY   A vCPU is already connected to the device.
      =======  ==========================================

2. KVM_DEV_XIVE_GRP_SOURCE (write only)
     Initializes a new source in the XIVE device and mask it.

  Attributes:
    Interrupt source number  (64-bit)

  The kvm_device_attr.addr points to a __u64 value::

    bits:     | 63   ....  2 |   1   |   0
    values:   |    unused    | level | type

  - type:  0:MSI 1:LSI
  - level: assertion level in case of an LSI.

  Errors:

    =======  ==========================================
    -E2BIG   Interrupt source number is out of range
    -ENOMEM  Could not create a new source block
    -EFAULT  Invalid user pointer for attr->addr.
    -ENXIO   Could not allocate underlying HW interrupt
    =======  ==========================================

3. KVM_DEV_XIVE_GRP_SOURCE_CONFIG (write only)
     Configures source targeting

  Attributes:
    Interrupt source number  (64-bit)

  The kvm_device_attr.addr points to a __u64 value::

    bits:     | 63   ....  33 |  32  | 31 .. 3 |  2 .. 0
    values:   |    eisn       | mask |  server | priority

  - priority: 0-7 interrupt priority level
  - server: CPU number chosen to handle the interrupt
  - mask: mask flag (unused)
  - eisn: Effective Interrupt Source Number

  Errors:

    =======  =======================================================
    -ENOENT  Unknown source number
    -EINVAL  Not initialized source number
    -EINVAL  Invalid priority
    -EINVAL  Invalid CPU number.
    -EFAULT  Invalid user pointer for attr->addr.
    -ENXIO   CPU event queues not configured or configuration of the
	     underlying HW interrupt failed
    -EBUSY   No CPU available to serve interrupt
    =======  =======================================================

4. KVM_DEV_XIVE_GRP_EQ_CONFIG (read-write)
     Configures an event queue of a CPU

  Attributes:
    EQ descriptor identifier (64-bit)

  The EQ descriptor identifier is a tuple (server, priority)::

    bits:     | 63   ....  32 | 31 .. 3 |  2 .. 0
    values:   |    unused     |  server | priority

  The kvm_device_attr.addr points to::

    struct kvm_ppc_xive_eq {
	__u32 flags;
	__u32 qshift;
	__u64 qaddr;
	__u32 qtoggle;
	__u32 qindex;
	__u8  pad[40];
    };

  - flags: queue flags
      KVM_XIVE_EQ_ALWAYS_NOTIFY (required)
	forces notification without using the coalescing mechanism
	provided by the XIVE END ESBs.
  - qshift: queue size (power of 2)
  - qaddr: real address of queue
  - qtoggle: current queue toggle bit
  - qindex: current queue index
  - pad: reserved for future use

  Errors:

    =======  =========================================
    -ENOENT  Invalid CPU number
    -EINVAL  Invalid priority
    -EINVAL  Invalid flags
    -EINVAL  Invalid queue size
    -EINVAL  Invalid queue address
    -EFAULT  Invalid user pointer for attr->addr.
    -EIO     Configuration of the underlying HW failed
    =======  =========================================

5. KVM_DEV_XIVE_GRP_SOURCE_SYNC (write only)
     Synchronize the source to flush event notifications

  Attributes:
    Interrupt source number  (64-bit)

  Errors:

    =======  =============================
    -ENOENT  Unknown source number
    -EINVAL  Not initialized source number
    =======  =============================

* VCPU state

  The XIVE IC maintains VP interrupt state in an internal structure
  called the NVT. When a VP is not dispatched on a HW processor
  thread, this structure can be updated by HW if the VP is the target
  of an event notification.

  It is important for migration to capture the cached IPB from the NVT
  as it synthesizes the priorities of the pending interrupts. We
  capture a bit more to report debug information.

  KVM_REG_PPC_VP_STATE (2 * 64bits)::

    bits:     |  63  ....  32  |  31  ....  0  |
    values:   |   TIMA word0   |   TIMA word1  |
    bits:     | 127       ..........       64  |
    values:   |            unused              |

* Migration:

  Saving the state of a VM using the XIVE native exploitation mode
  should follow a specific sequence. When the VM is stopped :

  1. Mask all sources (PQ=01) to stop the flow of events.

  2. Sync the XIVE device with the KVM control KVM_DEV_XIVE_EQ_SYNC to
  flush any in-flight event notification and to stabilize the EQs. At
  this stage, the EQ pages are marked dirty to make sure they are
  transferred in the migration sequence.

  3. Capture the state of the source targeting, the EQs configuration
  and the state of thread interrupt context registers.

  Restore is similar:

  1. Restore the EQ configuration. As targeting depends on it.
  2. Restore targeting
  3. Restore the thread interrupt contexts
  4. Restore the source states
  5. Let the vCPU run


code:
.. SPDX-License-Identifier: GPL-2.0

===========================
The KVM halt polling system
===========================

The KVM halt polling system provides a feature within KVM whereby the latency
of a guest can, under some circumstances, be reduced by polling in the host
for some time period after the guest has elected to no longer run by cedeing.
That is, when a guest vcpu has ceded, or in the case of powerpc when all of the
vcpus of a single vcore have ceded, the host kernel polls for wakeup conditions
before giving up the cpu to the scheduler in order to let something else run.

Polling provides a latency advantage in cases where the guest can be run again
very quickly by at least saving us a trip through the scheduler, normally on
the order of a few micro-seconds, although performance benefits are workload
dependant. In the event that no wakeup source arrives during the polling
interval or some other task on the runqueue is runnable the scheduler is
invoked. Thus halt polling is especially useful on workloads with very short
wakeup periods where the time spent halt polling is minimised and the time
savings of not invoking the scheduler are distinguishable.

The generic halt polling code is implemented in:

	virt/kvm/kvm_main.c: kvm_vcpu_block()

The powerpc kvm-hv specific case is implemented in:

	arch/powerpc/kvm/book3s_hv.c: kvmppc_vcore_blocked()

Halt Polling Interval
=====================

The maximum time for which to poll before invoking the scheduler, referred to
as the halt polling interval, is increased and decreased based on the perceived
effectiveness of the polling in an attempt to limit pointless polling.
This value is stored in either the vcpu struct:

	kvm_vcpu->halt_poll_ns

or in the case of powerpc kvm-hv, in the vcore struct:

	kvmppc_vcore->halt_poll_ns

Thus this is a per vcpu (or vcore) value.

During polling if a wakeup source is received within the halt polling interval,
the interval is left unchanged. In the event that a wakeup source isn't
received during the polling interval (and thus schedule is invoked) there are
two options, either the polling interval and total block time[0] were less than
the global max polling interval (see module params below), or the total block
time was greater than the global max polling interval.

In the event that both the polling interval and total block time were less than
the global max polling interval then the polling interval can be increased in
the hope that next time during the longer polling interval the wake up source
will be received while the host is polling and the latency benefits will be
received. The polling interval is grown in the function grow_halt_poll_ns() and
is multiplied by the module parameters halt_poll_ns_grow and
halt_poll_ns_grow_start.

In the event that the total block time was greater than the global max polling
interval then the host will never poll for long enough (limited by the global
max) to wakeup during the polling interval so it may as well be shrunk in order
to avoid pointless polling. The polling interval is shrunk in the function
shrink_halt_poll_ns() and is divided by the module parameter
halt_poll_ns_shrink, or set to 0 iff halt_poll_ns_shrink == 0.

It is worth noting that this adjustment process attempts to hone in on some
steady state polling interval but will only really do a good job for wakeups
which come at an approximately constant rate, otherwise there will be constant
adjustment of the polling interval.

[0] total block time:
		      the time between when the halt polling function is
		      invoked and a wakeup source received (irrespective of
		      whether the scheduler is invoked within that function).

Module Parameters
=================

The kvm module has 3 tuneable module parameters to adjust the global max
polling interval as well as the rate at which the polling interval is grown and
shrunk. These variables are defined in include/linux/kvm_host.h and as module
parameters in virt/kvm/kvm_main.c, or arch/powerpc/kvm/book3s_hv.c in the
powerpc kvm-hv case.

+-----------------------+---------------------------+-------------------------+
|Module Parameter	|   Description		    |	     Default Value    |
+-----------------------+---------------------------+-------------------------+
|halt_poll_ns		| The global max polling    | KVM_HALT_POLL_NS_DEFAULT|
|			| interval which defines    |			      |
|			| the ceiling value of the  |			      |
|			| polling interval for      | (per arch value)	      |
|			| each vcpu.		    |			      |
+-----------------------+---------------------------+-------------------------+
|halt_poll_ns_grow	| The value by which the    | 2			      |
|			| halt polling interval is  |			      |
|			| multiplied in the	    |			      |
|			| grow_halt_poll_ns()	    |			      |
|			| function.		    |			      |
+-----------------------+---------------------------+-------------------------+
|halt_poll_ns_grow_start| The initial value to grow | 10000		      |
|			| to from zero in the	    |			      |
|			| grow_halt_poll_ns()	    |			      |
|			| function.		    |			      |
+-----------------------+---------------------------+-------------------------+
|halt_poll_ns_shrink	| The value by which the    | 0			      |
|			| halt polling interval is  |			      |
|			| divided in the	    |			      |
|			| shrink_halt_poll_ns()	    |			      |
|			| function.		    |			      |
+-----------------------+---------------------------+-------------------------+

These module parameters can be set from the debugfs files in:

	/sys/module/kvm/parameters/

Note: that these module parameters are system wide values and are not able to
      be tuned on a per vm basis.

Any changes to these parameters will be picked up by new and existing vCPUs the
next time they halt, with the notable exception of VMs using KVM_CAP_HALT_POLL
(see next section).

KVM_CAP_HALT_POLL
=================

KVM_CAP_HALT_POLL is a VM capability that allows userspace to override halt_poll_ns
on a per-VM basis. VMs using KVM_CAP_HALT_POLL ignore halt_poll_ns completely (but
still obey halt_poll_ns_grow, halt_poll_ns_grow_start, and halt_poll_ns_shrink).

See Documentation/virt/kvm/api.rst for more information on this capability.

Further Notes
=============

- Care should be taken when setting the halt_poll_ns module parameter as a large value
  has the potential to drive the cpu usage to 100% on a machine which would be almost
  entirely idle otherwise. This is because even if a guest has wakeups during which very
  little work is done and which are quite far apart, if the period is shorter than the
  global max polling interval (halt_poll_ns) then the host will always poll for the
  entire block time and thus cpu utilisation will go to 100%.

- Halt polling essentially presents a trade off between power usage and latency and
  the module parameters should be used to tune the affinity for this. Idle cpu time is
  essentially converted to host kernel time with the aim of decreasing latency when
  entering the guest.

- Halt polling will only be conducted by the host when no other tasks are runnable on
  that cpu, otherwise the polling will cease immediately and schedule will be invoked to
  allow that other task to run. Thus this doesn't allow a guest to denial of service the
  cpu.


code:
.. SPDX-License-Identifier: GPL-2.0

===
KVM
===

.. toctree::
   :maxdepth: 2

   api
   devices/index

   arm/index
   s390/index
   ppc-pv
   x86/index

   locking
   vcpu-requests
   halt-polling
   review-checklist