POWER9 XIVE Gen1

XIVE device와 MMIO mapping

`KVM_DEV_TYPE_XIVE`는 POWER9 XIVE generation 1 interrupt controller를 guest VM에 제공합니다. Instance는 VM당 하나이며 host가 POWER9이고 guest OS가 XIVE native exploitation mode를 지원해야 합니다. 지원하지 않으면 POWER7/8 legacy XICS mode를 사용합니다.

KVM device는 interrupt management에 필요한 XIVE hardware MMIO range를 custom VM fault handler가 채우는 VMA로 guest에 노출합니다.

TIMA는 physical thread, hypervisor, operating-system, user privilege view 네 page를 가지며 guest에는 세 번째 OS page와 네 번째 user page만 노출됩니다.

Pass-through mapping 때 `kvmppc_xive_set_mapped()`·`kvmppc_xive_clr_mapped()`가 guest IRQ의 기존 ESB page를 clear하고 fault handler가 physical device HW interrupt ESB 또는 device 제거 뒤 초기 IPI ESB를 다시 삽입합니다. 이 remapping은 guest와 OS driver에 투명하며 VFIO와 KVM-PPC가 처리합니다.

.. 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 accommodate 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.

XIVE control, source와 event queue

`KVM_DEV_XIVE_GRP_SOURCE`는 새 source를 initialize하고 mask합니다. Attribute number가 interrupt source이고 `addr`의 64-bit 값에서 bit 0 type은 MSI=0·LSI=1, bit 1 level은 LSI assertion level입니다.

`KVM_DEV_XIVE_GRP_SOURCE_CONFIG`의 64-bit 값은 bit 2:0 priority, 31:3 server, bit 32 mask, 63:33 effective interrupt source number(EISN)를 encode합니다. Priority는 0~7이고 server는 interrupt를 처리할 CPU number입니다.

`KVM_DEV_XIVE_GRP_EQ_CONFIG` identifier는 bit 31:3 server와 bit 2:0 priority tuple입니다. `kvm_ppc_xive_eq`는 flags, queue-size power `qshift`, real address `qaddr`, current toggle과 index를 보존합니다.

EQ config에서 invalid CPU는 `-ENOENT`; priority·flag·size·address 오류는 `-EINVAL`; bad pointer는 `-EFAULT`; HW config 실패는 `-EIO`입니다.

`KVM_DEV_XIVE_GRP_SOURCE_SYNC`는 source number를 받아 event notification을 flush합니다. Unknown source는 `-ENOENT`, 미초기화 source는 `-EINVAL`입니다.

* 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
    =======  =============================

XIVE vCPU NVT state

XIVE interrupt controller는 VP interrupt state를 NVT internal structure에 유지합니다. VP가 hardware thread에 dispatch되지 않은 동안에도 event target이면 hardware가 NVT를 갱신할 수 있습니다.

Migration은 pending interrupt priority를 합성하는 NVT cached IPB를 반드시 포착해야 합니다. `KVM_REG_PPC_VP_STATE`는 128-bit 중 하위 64-bit에 TIMA word0과 word1을 각각 32-bit로 저장하고 상위 64-bit는 unused입니다.

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

XIVE migration sequence

* 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