Commit af280890 authored by David Woodhouse's avatar David Woodhouse Committed by Paolo Bonzini
Browse files

KVM: x86/xen: Documentation updates and clarifications 



Most notably, the KVM_XEN_EVTCHN_RESET feature had escaped documentation
entirely. Along with how to turn most stuff off on SHUTDOWN_soft_reset.

Signed-off-by: default avatarDavid Woodhouse <dwmw@amazon.co.uk>
Message-Id: <20221226120320.1125390-6-dwmw2@infradead.org>
Signed-off-by: default avatarPaolo Bonzini <pbonzini@redhat.com>
parent b0305c1e

Documentation/virt/kvm/api.rst

+26 −15
Original line number Diff line number Diff line
@@ -5343,9 +5343,9 @@ KVM_XEN_ATTR_TYPE_SHARED_INFO 
  32 vCPUs in the shared_info page, KVM does not automatically do so

  and instead requires that KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO be used

  explicitly even when the vcpu_info for a given vCPU resides at the

  "default" location in the shared_info page. This is because KVM is

  not aware of the Xen CPU id which is used as the index into the

  vcpu_info[] array, so cannot know the correct default location.

  "default" location in the shared_info page. This is because KVM may

  not be aware of the Xen CPU id which is used as the index into the

  vcpu_info[] array, so may know the correct default location.



  Note that the shared info page may be constantly written to by KVM;

  it contains the event channel bitmap used to deliver interrupts to
@@ -5356,23 +5356,29 @@ KVM_XEN_ATTR_TYPE_SHARED_INFO 
  any vCPU has been running or any event channel interrupts can be

  routed to the guest.



  Setting the gfn to KVM_XEN_INVALID_GFN will disable the shared info

  page.



KVM_XEN_ATTR_TYPE_UPCALL_VECTOR

  Sets the exception vector used to deliver Xen event channel upcalls.

  This is the HVM-wide vector injected directly by the hypervisor

  (not through the local APIC), typically configured by a guest via

  HVM_PARAM_CALLBACK_IRQ.

  HVM_PARAM_CALLBACK_IRQ. This can be disabled again (e.g. for guest

  SHUTDOWN_soft_reset) by setting it to zero.



KVM_XEN_ATTR_TYPE_EVTCHN

  This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates

  support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It configures

  an outbound port number for interception of EVTCHNOP_send requests

  from the guest. A given sending port number may be directed back

  to a specified vCPU (by APIC ID) / port / priority on the guest,

  or to trigger events on an eventfd. The vCPU and priority can be

  changed by setting KVM_XEN_EVTCHN_UPDATE in a subsequent call,

  but other fields cannot change for a given sending port. A port

  mapping is removed by using KVM_XEN_EVTCHN_DEASSIGN in the flags

  field.

  from the guest. A given sending port number may be directed back to

  a specified vCPU (by APIC ID) / port / priority on the guest, or to

  trigger events on an eventfd. The vCPU and priority can be changed

  by setting KVM_XEN_EVTCHN_UPDATE in a subsequent call, but but other

  fields cannot change for a given sending port. A port mapping is

  removed by using KVM_XEN_EVTCHN_DEASSIGN in the flags field. Passing

  KVM_XEN_EVTCHN_RESET in the flags field removes all interception of

  outbound event channels. The values of the flags field are mutually

  exclusive and cannot be combined as a bitmask.



KVM_XEN_ATTR_TYPE_XEN_VERSION

  This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates
@@ -5388,7 +5394,7 @@ KVM_XEN_ATTR_TYPE_RUNSTATE_UPDATE_FLAG 
  support for KVM_XEN_HVM_CONFIG_RUNSTATE_UPDATE_FLAG. It enables the

  XEN_RUNSTATE_UPDATE flag which allows guest vCPUs to safely read

  other vCPUs' vcpu_runstate_info. Xen guests enable this feature via

  the VM_ASST_TYPE_runstate_update_flag of the HYPERVISOR_vm_assist

  the VMASST_TYPE_runstate_update_flag of the HYPERVISOR_vm_assist

  hypercall.



4.127 KVM_XEN_HVM_GET_ATTR
@@ -5446,15 +5452,18 @@ KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO 
  As with the shared_info page for the VM, the corresponding page may be

  dirtied at any time if event channel interrupt delivery is enabled, so

  userspace should always assume that the page is dirty without relying

  on dirty logging.

  on dirty logging. Setting the gpa to KVM_XEN_INVALID_GPA will disable

  the vcpu_info.



KVM_XEN_VCPU_ATTR_TYPE_VCPU_TIME_INFO

  Sets the guest physical address of an additional pvclock structure

  for a given vCPU. This is typically used for guest vsyscall support.

  Setting the gpa to KVM_XEN_INVALID_GPA will disable the structure.



KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADDR

  Sets the guest physical address of the vcpu_runstate_info for a given

  vCPU. This is how a Xen guest tracks CPU state such as steal time.

  Setting the gpa to KVM_XEN_INVALID_GPA will disable the runstate area.



KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_CURRENT

  Sets the runstate (RUNSTATE_running/_runnable/_blocked/_offline) of
@@ -5487,7 +5496,8 @@ KVM_XEN_VCPU_ATTR_TYPE_TIMER 
  This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates

  support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It sets the

  event channel port/priority for the VIRQ_TIMER of the vCPU, as well

  as allowing a pending timer to be saved/restored.

  as allowing a pending timer to be saved/restored. Setting the timer

  port to zero disables kernel handling of the singleshot timer.



KVM_XEN_VCPU_ATTR_TYPE_UPCALL_VECTOR

  This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates
@@ -5495,7 +5505,8 @@ KVM_XEN_VCPU_ATTR_TYPE_UPCALL_VECTOR 
  per-vCPU local APIC upcall vector, configured by a Xen guest with

  the HVMOP_set_evtchn_upcall_vector hypercall. This is typically

  used by Windows guests, and is distinct from the HVM-wide upcall

  vector configured with HVM_PARAM_CALLBACK_IRQ.

  vector configured with HVM_PARAM_CALLBACK_IRQ. It is disabled by

  setting the vector to zero.





4.129 KVM_XEN_VCPU_GET_ATTR