hv: update virtual interrupts HLD

Signed-off-by: Yan, Like <like.yan@intel.com>

doc/developer-guides/hld/hv-virt-interrupt.rst

@@ -11,13 +11,16 @@ management, which includes:
 - physical-to-virtual interrupt mapping for a pass-thru device, and
 - the process of VMX interrupt/exception injection.
 
-A guest VM never owns any physical interrupts. All interrupts received by
+A standard VM never owns any physical interrupts, all interrupts received by
 Guest OS come from a virtual interrupt injected by vLAPIC, vIOAPIC or
 vPIC. Such virtual interrupts are triggered either from a pass-through
 device or from I/O mediators in SOS via hypercalls. The
 :ref:`interrupt-remapping` section discusses how the hypervisor manages
 the mapping between physical and virtual interrupts for pass-through
-devices.
+devices. However, a hard RT VM with LAPIC pass-through does own the physical
+maskable external interrupts. On its physical CPUs, interrupts are disabled
+in VMX root mode, while in VMX non-root mode, physical interrupts will be
+deliverd to RT VM directly.
 
 Emulation for devices is inside SOS user space device model, i.e.,
 acrn-dm. However for performance consideration: vLAPIC, vIOAPIC, and vPIC
@@ -46,6 +49,8 @@ physical vector 0xF0 is used to kick VCPU out of its VMX non-root mode,
 used to make a request for virtual interrupt injection or other
 requests such as flush EPT.
 
+.. note:: the IPI based vCPU request mechanism doesn't work for the hard RT VM.
+
 The eventid supported for virtual interrupt injection includes:
 
 .. doxygengroup:: virt_int_injection
@@ -60,8 +65,8 @@ VM-Exit. For some cases there is no need to send IPI when making a request,
 because the CPU making the request itself is the target VCPU. For
 example, the #GP exception request always happens on the current CPU when it
 finds an invalid emulation has happened. An external interrupt for a pass-thru
-device always happens on the VCPUs this device belonging to, so after it
+device always happens on the VCPUs of the VM which this device is belonged to,
-triggers an external-interrupt VM-Exit, the current CPU is also the
+so after it triggers an external-interrupt VM-Exit, the current CPU is the very
 target VCPU.
 
 Virtual LAPIC
@@ -85,14 +90,20 @@ vLAPIC provides the same features as the native LAPIC:
 vLAPIC APIs
 ===========
 
-APIs are provided when an interrupt source from vLAPIC needs to inject
+APIs are invoked when an interrupt source from vLAPIC needs to inject
 an interrupt, for example:
 
 - from LVT like LAPIC timer
 - from vIOAPIC for a pass-thru device interrupt
 - from an emulated device for a MSI
 
-These APIs will finish by making a request for *ACRN_REQUEST_EVENT.*
+These APIs will finish by making a vCPU request.
+_
+.. doxygenfunction:: vlapic_inject_intr
+  :project: Project ACRN
+
+.. doxygenfunction:: vlapic_set_intr
+  :project: Project ACRN
 
 .. doxygenfunction:: vlapic_set_local_intr
   :project: Project ACRN
@@ -100,7 +111,7 @@ These APIs will finish by making a request for *ACRN_REQUEST_EVENT.*
 .. doxygenfunction:: vlapic_intr_msi
   :project: Project ACRN
 
-.. doxygenfunction:: apicv_get_pir_desc_paddr
+.. doxygenfunction:: vlapic_receive_intr
   :project: Project ACRN
 
 EOI processing
@@ -113,24 +124,27 @@ case of EOI.
 In case of no APICv virtual interrupt delivery support, vLAPIC requires
 EOI from Guest OS whenever a vector was acknowledged and processed by
 guest. vLAPIC behavior is the same as HW LAPIC. Once an EOI is received,
-it clears the highest priority vector in ISR and TMR, and updates PPR
+it clears the highest priority vector in ISR, and updates PPR
-status. vLAPIC will then notify vIOAPIC if the corresponding vector
+status. vLAPIC will send an EOI message to vIOAPIC if the TMR bit is set to
-comes from vIOAPIC. This only occurs for the level triggered interrupts.
+indicate that is a level triggered interrupt.
 
 .. _lapic_passthru:
 
 LAPIC passthrough based on vLAPIC
 =================================
 
-LAPIC passthrough is supported based on vLAPIC, after switch to x2APIC
+LAPIC passthrough is supported based on vLAPIC, guest OS firstly boots with
-mode. In case of LAPIC passthrough based on vLAPIC, the system will have the
+vLAPIC in xAPIC mode and then switches to x2APIC mode to enable the LAPIC
+pass-through.
+
+In case of LAPIC passthrough based on vLAPIC, the system will have the
 following characteristics.
 
 * IRQs received by the LAPIC can be handled by the Guest VM without ``vmexit``
-* Guest VM always see virtual LAPIC IDs for security reasons
+* Guest VM always see virtual LAPIC IDs for security consideration
 * most MSRs are directly accessible from Guest VM except for ``XAPICID``,
   ``LDR`` and ``ICR``. Write operations to ``ICR`` will be trapped to avoid
-  malicious IPI. Read operations to ``XAPIC`` and ``LDR`` will be trapped in
+  malicious IPIs. Read operations to ``XAPIC`` and ``LDR`` will be trapped in
   order to make the Guest VM always see the virtual LAPIC IDs instead of the
   physical ones.
 
@@ -139,7 +153,7 @@ Virtual IOAPIC
 
 vIOAPIC is emulated by HV when Guest accesses MMIO GPA range:
 0xFEC00000-0xFEC01000. vIOAPIC for SOS should match to the native HW
-IOAPIC Pin numbers. vIOAPIC for UOS provides 48 Pins. As the vIOAPIC is
+IOAPIC Pin numbers. vIOAPIC for guest VM provides 48 pins. As the vIOAPIC is
 always associated with vLAPIC, the virtual interrupt injection from
 vIOAPIC will finally trigger a request for vLAPIC event by calling
 vLAPIC APIs.
@@ -155,8 +169,8 @@ vLAPIC APIs.
 Virtual PIC
 ***********
 
-vPIC is required for TSC calculation. Normally UOS will boot with
+vPIC is required for TSC calculation. Normally guest OS will boot with
-vIOAPIC and vPIC as the source of external interrupts to Guest. On every
+vIOAPIC and vPIC as the source of external interrupts. On every
 VM Exit, HV will check if there are any pending external PIC interrupts.
 vPIC APIs usage are similar to vIOAPIC.
 
@@ -188,20 +202,14 @@ hypervisor, for example:
 
 - if guest accesses an invalid vMSR register,
 - hypervisor needs to inject a #GP, or 
-- during instruction emulation, an instruction fetch may access
+- hypervisor needs to inject #PF when an instruction accesses a non-exist page
-  a non-exist page from rip_gva, at that time a #PF need be injected.
+  from rip_gva during instruction emulation.
 
 ACRN hypervisor implements virtual exception injection using these APIs:
 
 .. doxygenfunction:: vcpu_queue_exception
   :project: Project ACRN
 
-.. doxygenfunction:: vcpu_inject_extint
-  :project: Project ACRN
-
-.. doxygenfunction:: vcpu_inject_nmi
-  :project: Project ACRN
-
 .. doxygenfunction:: vcpu_inject_gp
   :project: Project ACRN
 
@@ -218,6 +226,15 @@ ACRN hypervisor uses the *vcpu_inject_gp/vcpu_inject_pf* functions
 to queue exception request, and follows SDM vol3 - 6.15, Table 6-5 to
 generate double fault if the condition is met.
 
+ACRN hypervisor could inject *extint/nmi* using the similar vcpu APIs:
+
+.. doxygenfunction:: vcpu_inject_extint
+  :project: Project ACRN
+
+.. doxygenfunction:: vcpu_inject_nmi
+  :project: Project ACRN
+
+
 .. _virt-interrupt-injection:
 
 Virtual Interrupt Injection
@@ -226,22 +243,24 @@ Virtual Interrupt Injection
 The source of virtual interrupts comes from either DM or assigned
 devices.
 
--  **For SOS assigned devices**: as all devices are assigned to SOS
+-  **For Service VM assigned devices**: as most devices are assigned to the
-   directly. Whenever there is a device's physical interrupt, the
+   Service VM directly. Whenever there is a physical interrupt from an assigned
-   corresponding virtual interrupts are injected to SOS via
+   device, the corresponding virtual interrupt will be injected to the Service
-   vLAPIC/vIOAPIC. SOS does not use vPIC and does not have emulated
+   VM via vLAPIC/vIOAPIC. See :ref:`device-assignment`.
-   devices. See :ref:`device-assignment`.
 
--  **For UOS assigned devices**: only PCI devices could be assigned to
+-  **For User VM assigned devices**: only PCI devices could be assigned to
-   UOS. Virtual interrupt injection follows the same way as SOS. A
+   Uer VM. For the standard VM and soft RT VM, the virtual interrupt
-   virtual interrupt injection operation is triggered when a
+   injection follows the same way as Servic VM. A virtual interrupt injection
-   device's physical interrupt occurs.
+   operation is triggered when a device's physical interrupt occurs. For the
+   hard RT VM, the physical interrupts are delieverd to VM directly without
+   causing VM-exit.
 
--  **For UOS emulated devices**: DM (acrn-dm) is responsible for UOS
+-  **For User VM emulated devices**: DM is responsible for the
    emulated devices' interrupt lifecycle management. DM knows when
    an emulated device needs to assert a virtual IOPAIC/PIC Pin or
    needs to send a virtual MSI vector to Guest. These logic is
-   entirely handled by DM.
+   entirely handled by DM. For the hard RT VM, there should be no
+   emulated devices.
 
 .. figure:: images/virtint-image64.png
    :align: center
@@ -255,9 +274,9 @@ that Guest ``RFLAGS.IF`` gets cleared and it would not accept any further
 interrupts. HV will check for the available Guest IRQ windows before
 injection.
 
-NMI is unmasked interrupt and its injection is always allowed
+NMI is unmaskable interrupt and its injection is always allowed
 regardless of the guest IRQ window status. If current IRQ
-windows is not present, HV would enable
+window is not present, HV would enable
 ``MSR_IA32_VMX_PROCBASED_CTLS_IRQ_WIN (PROCBASED_CTRL.bit[2])`` and
 VM Enter directly. The injection will be done on next VM Exit once Guest
 issues ``STI (GuestRFLAG.IF=1)``.