From 72faca506883874848bc8148f6819899e1661a42 Mon Sep 17 00:00:00 2001
From: "Yan, Like" <like.yan@intel.com>
Date: Thu, 24 Jan 2019 20:04:33 +0800
Subject: [PATCH] doc: update documents for "--lapic_pt" feature

- added description of lapic pt feature based on vlapic in HLD virt-interrupt part;
- updated the doc to include description of new acrn-dm option "--lapic_pt".

Tracked-On: #2351
Signed-off-by: Yan, Like <like.yan@intel.com>
Acked-by: Anthony Xu <anthony.xu@intel.com>
---
 doc/developer-guides/hld/hld-devicemodel.rst   |  4 +++-
 doc/developer-guides/hld/hv-virt-interrupt.rst | 15 +++++++++++++++
 doc/user-guides/acrn-dm-parameters.rst         |  7 +++++++
 3 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/doc/developer-guides/hld/hld-devicemodel.rst b/doc/developer-guides/hld/hld-devicemodel.rst
index 426eb2b14..154e65404 100644
--- a/doc/developer-guides/hld/hld-devicemodel.rst
+++ b/doc/developer-guides/hld/hld-devicemodel.rst
@@ -57,7 +57,8 @@ options:
                [-s pci] [-U uuid] [--vsbl vsbl_file_name] [--ovmf ovmf_file_path]
                [--part_info part_info_name] [--enable_trusty] [--intr_monitor param_setting]
                [--vtpm2 sock_path] [--virtio_poll interval] [--mac_seed seed_string]
-               [--vmcfg sub_options] [--dump vm_idx] [--ptdev_no_reset] [--debugexit] <vm>
+               [--vmcfg sub_options] [--dump vm_idx] [--ptdev_no_reset] [--debugexit]
+               [--lapic_pt] <vm>
        -A: create ACPI tables
        -B: bootargs for kernel
        -c: # cpus (default 1)
@@ -88,6 +89,7 @@ options:
             its params: threshold/s,probe-period(s),delay_time(ms),delay_duration(ms),
        --virtio_poll: enable virtio poll mode with poll interval with ns
        --vtpm2: Virtual TPM2 args: sock_path=$PATH_OF_SWTPM_SOCKET
+       --lapic_pt: enable local apic passthrough
 
 See :ref:`acrn-dm_parameters` for more detailed descriptions of these
 configuration options.
diff --git a/doc/developer-guides/hld/hv-virt-interrupt.rst b/doc/developer-guides/hld/hv-virt-interrupt.rst
index 429d45a89..1e201cb80 100644
--- a/doc/developer-guides/hld/hv-virt-interrupt.rst
+++ b/doc/developer-guides/hld/hv-virt-interrupt.rst
@@ -126,6 +126,21 @@ it clears the highest priority vector in ISR and TMR, and updates PPR
 status. vLAPIC will then notify vIOAPIC if the corresponding vector
 comes from vIOAPIC. This only occurs for the level triggered interrupts.
 
+LAPIC passthrough based on vLAPIC
+=================================
+
+LAPIC passthrough is supported based on vLAPIC, after switch to x2APIC
+mode. 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
+* 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
+  order to make the Guest VM always see the virtual LAPIC IDs instead of the
+  physical ones.
+
 Virtual IOAPIC
 **************
 
diff --git a/doc/user-guides/acrn-dm-parameters.rst b/doc/user-guides/acrn-dm-parameters.rst
index f7aeee2a3..aaa06c063 100644
--- a/doc/user-guides/acrn-dm-parameters.rst
+++ b/doc/user-guides/acrn-dm-parameters.rst
@@ -313,3 +313,10 @@ Here are descriptions for each of these ``acrn-dm`` command line parameters:
 
        By default, DM will create the MPtable for you. Use this option to
        disable it.
+
+   * - :kbd:`--lapic_pt`
+     - This option is to create a VM with lapic pass-through.
+       With this option, a VM is created with LAPIC_PASSTHROUGH and
+       IOREQ_COMPLETION_POLLING mode. This kind of VM is generally for realtime scenarios.
+
+       By default, DM will create VM without this option.