doc:Update hypercall and upcall

update hld for hypercall and upcall

Signed-off-by: Mingqiang Chi <mingqiang.chi@intel.com>

doc/developer-guides/hld/hld-security.rst

@@ -519,6 +519,8 @@ or the SOS device model process, in case its memory content is
 re-allocated to another guest VM which could otherwise leave the
 previous guest VM secrets in memory.
 
+.. _secure-hypervisor-interface:
+
 Secure Hypervisor Interface
 ---------------------------
 

doc/developer-guides/hld/hv-hypercall.rst

@@ -3,19 +3,36 @@
 Hypercall / VHM upcall
 ######################
 
-HV currently supports hypercall APIs for VM management, I/O request
+Hypercall/upcall used to request services between Guest VM and hypervisor,
-distribution, and guest memory mapping.
+hypercall is from Guest VM to hypervisor, upcall is from hypervisor to Guest VM.
+Hypervisor currently supports hypercall APIs for VM management, I/O request
+distribution,interrupt injection, PCI assignment, guest memory mapping,
+power management and secure world switch.
 
-HV and Service OS (SOS) also use vector 0xF7, reserved as x86 platform
+There are some restrictions for hypercall and upcall:
+
+#. Only ring0 hypercalls from the guest VM are handled by the hypervisor,
+   otherwise hypervisor will inject GP to Guest VM.
+#. All the hypercalls (except secure world hypercalls) must be called from SOS VM,
+   otherwise hypervisor will inject UD to Guest VM.
+   see :ref:`secure-hypervisor-interface` for a detailed description.
+#. Hypervisor needs to protect the critical resources such as global VM and VCPU structures
+   for VM and VCPU management hypercalls.
+#. Upcall is only used for SOS VM.
+
+
+HV and Service OS (SOS) both use the same vector(0xF3) reserved as x86 platform
 IPI vector for HV notification to SOS. This upcall is necessary whenever
-there is device emulation requirement to SOS. The upcall vector 0xF7 is
+there is device emulation requirement to SOS. The upcall vector(0xF3) is
-injected to SOS vCPU0
+injected to SOS vCPU0.SOS will register the irq handler for vector(0xF3) and notify the I/O emulation
-
-SOS will register the irq handler for 0xF7 and notify the I/O emulation
 module in SOS once the irq is triggered.
+The detailed upcall process see :ref:`ipi-management`
+
+Hypercall APIs reference:
+*************************
+
+:ref:`hypercall_apis` for SOS
+
+:ref:`trusty-hypercalls` for Trusty
 
 
-.. note:: Add API doc references for General interface, VM management
-   interface, IRQ and Interrupts, Device Model IO request distribution,
-   Guest memory management, PCI assignment and IOMMU, Debug, Trusty, Power
-   management

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

@@ -358,13 +358,13 @@ IPI Management
 The only purpose of IPI use in HV is to kick a vCPU out of non-root mode
 and enter to HV mode. This requires I/O request and virtual interrupt
 injection be distributed to different IPI vectors. The I/O request uses
-IPI vector 0xF4 upcall. The virtual interrupt injection uses IPI vector 0xF0.
+IPI vector 0xF3 upcall. The virtual interrupt injection uses IPI vector 0xF0.
 
-0xF4 upcall
+0xF3 upcall
    A Guest vCPU VM Exit exits due to EPT violation or IO instruction trap.
    It requires Device Module to emulate the MMIO/PortIO instruction.
    However it could be that the Service OS (SOS) vCPU0 is still in non-root
-   mode. So an IPI (0xF4 upcall vector) should be sent to the physical CPU0
+   mode. So an IPI (0xF3 upcall vector) should be sent to the physical CPU0
    (with non-root mode as vCPU0 inside SOS) to force vCPU0 to VM Exit due
    to the external interrupt. The virtual upcall vector is then injected to
    SOS, and the vCPU0 inside SOS then will pick up the IO request and do

doc/developer-guides/trusty.rst

@@ -33,6 +33,8 @@ Trusty Architecture
 .. note::
    Trusty OS is running in Secure World in the architecture drawing above.
 
+.. _trusty-hypercalls:
+
 Trusty specific Hypercalls
 **************************