Documentation/virt/kvm/devices/xics.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =========================
   4 XICS interrupt controller
   5 =========================
   6
   7 Device type supported: KVM_DEV_TYPE_XICS
   8
   9 Groups:
  10   1. KVM_DEV_XICS_GRP_SOURCES
  11        Attributes:
  12
  13          One per interrupt source, indexed by the source number.
  14   2. KVM_DEV_XICS_GRP_CTRL
  15        Attributes:
  16
  17          2.1 KVM_DEV_XICS_NR_SERVERS (write only)
  18
  19   The kvm_device_attr.addr points to a __u32 value which is the number of
  20   interrupt server numbers (ie, highest possible vcpu id plus one).
  21
  22   Errors:
  23
  24     =======  ==========================================
  25     -EINVAL  Value greater than KVM_MAX_VCPU_IDS.
  26     -EFAULT  Invalid user pointer for attr->addr.
  27     -EBUSY   A vcpu is already connected to the device.
  28     =======  ==========================================
  29
  30 This device emulates the XICS (eXternal Interrupt Controller
  31 Specification) defined in PAPR.  The XICS has a set of interrupt
  32 sources, each identified by a 20-bit source number, and a set of
  33 Interrupt Control Presentation (ICP) entities, also called "servers",
  34 each associated with a virtual CPU.
  35
  36 The ICP entities are created by enabling the KVM_CAP_IRQ_ARCH
  37 capability for each vcpu, specifying KVM_CAP_IRQ_XICS in args[0] and
  38 the interrupt server number (i.e. the vcpu number from the XICS's
  39 point of view) in args[1] of the kvm_enable_cap struct.  Each ICP has
  40 64 bits of state which can be read and written using the
  41 KVM_GET_ONE_REG and KVM_SET_ONE_REG ioctls on the vcpu.  The 64 bit
  42 state word has the following bitfields, starting at the
  43 least-significant end of the word:
  44
  45 * Unused, 16 bits
  46
  47 * Pending interrupt priority, 8 bits
  48   Zero is the highest priority, 255 means no interrupt is pending.
  49
  50 * Pending IPI (inter-processor interrupt) priority, 8 bits
  51   Zero is the highest priority, 255 means no IPI is pending.
  52
  53 * Pending interrupt source number, 24 bits
  54   Zero means no interrupt pending, 2 means an IPI is pending
  55
  56 * Current processor priority, 8 bits
  57   Zero is the highest priority, meaning no interrupts can be
  58   delivered, and 255 is the lowest priority.
  59
  60 Each source has 64 bits of state that can be read and written using
  61 the KVM_GET_DEVICE_ATTR and KVM_SET_DEVICE_ATTR ioctls, specifying the
  62 KVM_DEV_XICS_GRP_SOURCES attribute group, with the attribute number being
  63 the interrupt source number.  The 64 bit state word has the following
  64 bitfields, starting from the least-significant end of the word:
  65
  66 * Destination (server number), 32 bits
  67
  68   This specifies where the interrupt should be sent, and is the
  69   interrupt server number specified for the destination vcpu.
  70
  71 * Priority, 8 bits
  72
  73   This is the priority specified for this interrupt source, where 0 is
  74   the highest priority and 255 is the lowest.  An interrupt with a
  75   priority of 255 will never be delivered.
  76
  77 * Level sensitive flag, 1 bit
  78
  79   This bit is 1 for a level-sensitive interrupt source, or 0 for
  80   edge-sensitive (or MSI).
  81
  82 * Masked flag, 1 bit
  83
  84   This bit is set to 1 if the interrupt is masked (cannot be delivered
  85   regardless of its priority), for example by the ibm,int-off RTAS
  86   call, or 0 if it is not masked.
  87
  88 * Pending flag, 1 bit
  89
  90   This bit is 1 if the source has a pending interrupt, otherwise 0.
  91
  92 Only one XICS instance may be created per VM.