hv: hypercalls: refactor permission-checking and dispatching logic

The current permission-checking and dispatching mechanism of hypercalls is
not unified because:

  1. Some hypercalls require the exact vCPU initiating the call, while the
     others only need to know the VM.
  2. Different hypercalls have different permission requirements: the
     trusty-related ones are enabled by a guest flag, while the others
     require the initiating VM to be the Service OS.

Without a unified logic it could be hard to scale when more kinds of
hypercalls are added later.

The objectives of this patch are as follows.

  1. All hypercalls have the same prototype and are dispatched by a unified
     logic.
  2. Permissions are checked by a unified logic without consulting the
     hypercall ID.

To achieve the first objective, this patch modifies the type of the first
parameter of hcall_* functions (which are the callbacks implementing the
hypercalls) from `struct acrn_vm *` to `struct acrn_vcpu *`. The
doxygen-style documentations are updated accordingly.

To achieve the second objective, this patch adds to `struct hc_dispatch` a
`permission_flags` field which specifies the guest flags that must ALL be
set for a VM to be able to invoke the hypercall. The default value (which
is 0UL) indicates that this hypercall is for SOS only. Currently only the
`permission_flag` of trusty-related hypercalls have the non-zero value
GUEST_FLAG_SECURE_WORLD_ENABLED.

With `permission_flag`, the permission checking logic of hypercalls is
unified as follows.

  1. General checks
     i. If the VM is neither SOS nor having any guest flag that allows
        certain hypercalls, it gets #UD upon executing the `vmcall`
        instruction.
    ii. If the VM is allowed to execute the `vmcall` instruction, but
        attempts to execute it in ring 1, 2 or 3, the VM gets #GP(0).
  2. Hypercall-specific checks
     i. If the hypercall is for SOS (i.e. `permission_flag` is 0), the
        initiating VM must be SOS and the specified target VM cannot be a
        pre-launched VM. Otherwise the hypercall returns -EINVAL without
        further actions.
    ii. If the hypercall requires certain guest flags, the initiating VM
        must have all the required flags. Otherwise the hypercall returns
        -EINVAL without further actions.
   iii. A hypercall with an unknown hypercall ID makes the hypercall
        returns -EINVAL without further actions.

The logic above is different from the current implementation in the
following aspects.

  1. A pre-launched VM now gets #UD (rather than #GP(0)) when it attempts
     to execute `vmcall` in ring 1, 2 or 3.
  2. A pre-launched VM now gets #UD (rather than the return value -EPERM)
     when it attempts to execute a trusty hypercall in ring 0.
  3. The SOS now gets the return value -EINVAL (rather than -EPERM) when it
     attempts to invoke a trusty hypercall.
  4. A post-launched VM with trusty support now gets the return value
     -EINVAL (rather than #UD) when it attempts to invoke a non-trusty
     hypercall or an invalid hypercall.

v1 -> v2:
 - Update documentation that describe hypercall behavior.
 - Fix Doxygen warnings

Tracked-On: #5924
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
Acked-by: Eddie Dong <eddie.dong@intel.com>

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

@@ -599,13 +599,16 @@ As shown in :numref:`security-hir`, there are some restrictions for
 hypercall invocation in the hypervisor design:
 
 #. Hypercalls from ring 1~3 of any guest VM are not allowed. The
-   hypervisor must discard such hypercalls silently. Only ring-0
+   hypervisor must discard such hypercalls and inject ``#GP(0)`` instead. Only ring-0
    hypercalls from the guest VM are handled by the hypervisor.
 #. All the hypercalls (except world\_switch hypercall) must be called
    from the ring-0 driver of the Service VM.
    World\_switch Hypercall is used by the TIPC (Trusty IPC) driver to
    switch guest VM context between secure world and non-secure world.
    Further details will be discussed in the :ref:`secure_trusty` section.
+   When a vCPU issues an unpermitted hypercall, the hypervisor shall either
+   inject ``#UD`` (if the VM cannot issue hypercalls at all) or return ``-EINVAL``
+   (if the VM is allowed to issue hypercalls but not this specific one).
 #. For those hypercalls that may result in data inconsistent intra hypervisor
    when they are executed concurrently, such as ``hcall_create_vm()``
    ``hcll_destroy_vm()`` etc. spinlock is used to ensure these hypercalls

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

@@ -11,10 +11,16 @@ power management, and secure world switch.
 
 There are some restrictions for hypercall and upcall:
 
+#. Only specific VMs (currently the Service VM and the VM with trusty enabled)
+   can invoke hypercalls. A VM that cannot invoke hypercalls will get ``#UD``
+   (i.e. invalid opcode exception).
 #. Only ring 0 hypercalls from the guest VM are handled by the hypervisor;
-   otherwise, the hypervisor will inject GP to the Guest VM.
-#. All the hypercalls (except secure world hypercalls) must be called from the Service VM;
-   otherwise, the hypervisor will inject UD to the Guest VM.
+   otherwise, the hypervisor will inject ``#GP(0)`` (i.e. generation protection
+   exception with error code ``0``) to the Guest VM.
+#. Each VM is permitted to invoke a certain subset of hypercalls. Currently a VM
+   with trusty enabled is allowed to invoke trusty hypercalls, and the Service
+   VM is allowed to invoke the other hypercalls. A VM that invokes an
+   unpermitted hypercall will get the return value ``-EINVAL``.
    see :ref:`secure-hypervisor-interface` for a detailed description.
 #. The hypervisor needs to protect the critical resources such as global VM and VCPU structures
    for VM and VCPU management hypercalls.