From 343aabca4b142d87558eda111b7b31310c8e249c Mon Sep 17 00:00:00 2001 From: Mingqiang Chi Date: Tue, 15 Oct 2019 12:08:12 +0800 Subject: [PATCH] doc:Update hypercall and upcall update hld for hypercall and upcall Signed-off-by: Mingqiang Chi --- doc/developer-guides/hld/hld-security.rst | 2 ++ doc/developer-guides/hld/hv-hypercall.rst | 39 ++++++++++++++++------- doc/developer-guides/hld/hv-interrupt.rst | 6 ++-- doc/developer-guides/trusty.rst | 2 ++ 4 files changed, 35 insertions(+), 14 deletions(-) diff --git a/doc/developer-guides/hld/hld-security.rst b/doc/developer-guides/hld/hld-security.rst index 5933c9e9f..7af07d294 100644 --- a/doc/developer-guides/hld/hld-security.rst +++ b/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 --------------------------- diff --git a/doc/developer-guides/hld/hv-hypercall.rst b/doc/developer-guides/hld/hv-hypercall.rst index dc13f912e..ed1aad75b 100644 --- a/doc/developer-guides/hld/hv-hypercall.rst +++ b/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 -distribution, and guest memory mapping. +Hypercall/upcall used to request services between Guest VM and hypervisor, +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 -injected to SOS vCPU0 - -SOS will register the irq handler for 0xF7 and notify the I/O emulation +there is device emulation requirement to SOS. The upcall vector(0xF3) is +injected to SOS vCPU0.SOS will register the irq handler for vector(0xF3) 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 diff --git a/doc/developer-guides/hld/hv-interrupt.rst b/doc/developer-guides/hld/hv-interrupt.rst index 93a4575d2..e9164213f 100644 --- a/doc/developer-guides/hld/hv-interrupt.rst +++ b/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 diff --git a/doc/developer-guides/trusty.rst b/doc/developer-guides/trusty.rst index e9784aafd..9a8cf31ca 100644 --- a/doc/developer-guides/trusty.rst +++ b/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 **************************