Documentation/virt/kvm/devices/vcpu.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ======================
   4 Generic vcpu interface
   5 ======================
   6
   7 The virtual cpu "device" also accepts the ioctls KVM_SET_DEVICE_ATTR,
   8 KVM_GET_DEVICE_ATTR, and KVM_HAS_DEVICE_ATTR. The interface uses the same struct
   9 kvm_device_attr as other devices, but targets VCPU-wide settings and controls.
  10
  11 The groups and attributes per virtual cpu, if any, are architecture specific.
  12
  13 1. GROUP: KVM_ARM_VCPU_PMU_V3_CTRL
  14 ==================================
  15
  16 :Architectures: ARM64
  17
  18 1.1. ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_IRQ
  19 ---------------------------------------
  20
  21 :Parameters: in kvm_device_attr.addr the address for PMU overflow interrupt is a
  22              pointer to an int
  23
  24 Returns:
  25
  26          =======  ========================================================
  27          -EBUSY   The PMU overflow interrupt is already set
  28          -EFAULT  Error reading interrupt number
  29          -ENXIO   PMUv3 not supported or the overflow interrupt not set
  30                   when attempting to get it
  31          -ENODEV  KVM_ARM_VCPU_PMU_V3 feature missing from VCPU
  32          -EINVAL  Invalid PMU overflow interrupt number supplied or
  33                   trying to set the IRQ number without using an in-kernel
  34                   irqchip.
  35          =======  ========================================================
  36
  37 A value describing the PMUv3 (Performance Monitor Unit v3) overflow interrupt
  38 number for this vcpu. This interrupt could be a PPI or SPI, but the interrupt
  39 type must be same for each vcpu. As a PPI, the interrupt number is the same for
  40 all vcpus, while as an SPI it must be a separate number per vcpu.
  41
  42 1.2 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_INIT
  43 ---------------------------------------
  44
  45 :Parameters: no additional parameter in kvm_device_attr.addr
  46
  47 Returns:
  48
  49          =======  ======================================================
  50          -EEXIST  Interrupt number already used
  51          -ENODEV  PMUv3 not supported or GIC not initialized
  52          -ENXIO   PMUv3 not supported, missing VCPU feature or interrupt
  53                   number not set
  54          -EBUSY   PMUv3 already initialized
  55          =======  ======================================================
  56
  57 Request the initialization of the PMUv3.  If using the PMUv3 with an in-kernel
  58 virtual GIC implementation, this must be done after initializing the in-kernel
  59 irqchip.
  60
  61 1.3 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_FILTER
  62 -----------------------------------------
  63
  64 :Parameters: in kvm_device_attr.addr the address for a PMU event filter is a
  65              pointer to a struct kvm_pmu_event_filter
  66
  67 :Returns:
  68
  69          =======  ======================================================
  70          -ENODEV  PMUv3 not supported or GIC not initialized
  71          -ENXIO   PMUv3 not properly configured or in-kernel irqchip not
  72                   configured as required prior to calling this attribute
  73          -EBUSY   PMUv3 already initialized
  74          -EINVAL  Invalid filter range
  75          =======  ======================================================
  76
  77 Request the installation of a PMU event filter described as follows::
  78
  79     struct kvm_pmu_event_filter {
  80             __u16       base_event;
  81             __u16       nevents;
  82
  83     #define KVM_PMU_EVENT_ALLOW 0
  84     #define KVM_PMU_EVENT_DENY  1
  85
  86             __u8        action;
  87             __u8        pad[3];
  88     };
  89
  90 A filter range is defined as the range [@base_event, @base_event + @nevents),
  91 together with an @action (KVM_PMU_EVENT_ALLOW or KVM_PMU_EVENT_DENY). The
  92 first registered range defines the global policy (global ALLOW if the first
  93 @action is DENY, global DENY if the first @action is ALLOW). Multiple ranges
  94 can be programmed, and must fit within the event space defined by the PMU
  95 architecture (10 bits on ARMv8.0, 16 bits from ARMv8.1 onwards).
  96
  97 Note: "Cancelling" a filter by registering the opposite action for the same
  98 range doesn't change the default action. For example, installing an ALLOW
  99 filter for event range [0:10) as the first filter and then applying a DENY
 100 action for the same range will leave the whole range as disabled.
 101
 102 Restrictions: Event 0 (SW_INCR) is never filtered, as it doesn't count a
 103 hardware event. Filtering event 0x1E (CHAIN) has no effect either, as it
 104 isn't strictly speaking an event. Filtering the cycle counter is possible
 105 using event 0x11 (CPU_CYCLES).
 106
 107
 108 2. GROUP: KVM_ARM_VCPU_TIMER_CTRL
 109 =================================
 110
 111 :Architectures: ARM, ARM64
 112
 113 2.1. ATTRIBUTES: KVM_ARM_VCPU_TIMER_IRQ_VTIMER, KVM_ARM_VCPU_TIMER_IRQ_PTIMER
 114 -----------------------------------------------------------------------------
 115
 116 :Parameters: in kvm_device_attr.addr the address for the timer interrupt is a
 117              pointer to an int
 118
 119 Returns:
 120
 121          =======  =================================
 122          -EINVAL  Invalid timer interrupt number
 123          -EBUSY   One or more VCPUs has already run
 124          =======  =================================
 125
 126 A value describing the architected timer interrupt number when connected to an
 127 in-kernel virtual GIC.  These must be a PPI (16 <= intid < 32).  Setting the
 128 attribute overrides the default values (see below).
 129
 130 =============================  ==========================================
 131 KVM_ARM_VCPU_TIMER_IRQ_VTIMER  The EL1 virtual timer intid (default: 27)
 132 KVM_ARM_VCPU_TIMER_IRQ_PTIMER  The EL1 physical timer intid (default: 30)
 133 =============================  ==========================================
 134
 135 Setting the same PPI for different timers will prevent the VCPUs from running.
 136 Setting the interrupt number on a VCPU configures all VCPUs created at that
 137 time to use the number provided for a given timer, overwriting any previously
 138 configured values on other VCPUs.  Userspace should configure the interrupt
 139 numbers on at least one VCPU after creating all VCPUs and before running any
 140 VCPUs.
 141
 142 3. GROUP: KVM_ARM_VCPU_PVTIME_CTRL
 143 ==================================
 144
 145 :Architectures: ARM64
 146
 147 3.1 ATTRIBUTE: KVM_ARM_VCPU_PVTIME_IPA
 148 --------------------------------------
 149
 150 :Parameters: 64-bit base address
 151
 152 Returns:
 153
 154          =======  ======================================
 155          -ENXIO   Stolen time not implemented
 156          -EEXIST  Base address already set for this VCPU
 157          -EINVAL  Base address not 64 byte aligned
 158          =======  ======================================
 159
 160 Specifies the base address of the stolen time structure for this VCPU. The
 161 base address must be 64 byte aligned and exist within a valid guest memory
 162 region. See Documentation/virt/kvm/arm/pvtime.rst for more information
 163 including the layout of the stolen time structure.