From e967fb327f104300b6ab76b5f09f83a5c3bd73ed Mon Sep 17 00:00:00 2001
From: Li Fei1 <fei1.li@intel.com>
Date: Thu, 23 Jul 2020 11:29:54 +0800
Subject: [PATCH] doc: add mmio device passthrough introduction

Besides PCI passthru, ACRN can support passthru of a set of page-aligned
MMIO resources. One example is to passthru a TPM device which includes
a set of page aligned MMIO resources.

Signed-off-by: Li Fei1 <fei1.li@intel.com>
---
 doc/developer-guides/hld/hld-devicemodel.rst  |  8 +++-
 .../hld/mmio-dev-passthrough.rst              | 40 +++++++++++++++++++
 2 files changed, 47 insertions(+), 1 deletion(-)
 create mode 100644 doc/developer-guides/hld/mmio-dev-passthrough.rst

diff --git a/doc/developer-guides/hld/hld-devicemodel.rst b/doc/developer-guides/hld/hld-devicemodel.rst
index 2545d6f03..5a2e340ae 100644
--- a/doc/developer-guides/hld/hld-devicemodel.rst
+++ b/doc/developer-guides/hld/hld-devicemodel.rst
@@ -56,6 +56,7 @@ options:
                [-l lpc] [-m mem] [-p vcpu:hostcpu] [-r ramdisk_image_path]
                [-s pci] [-U uuid] [--vsbl vsbl_file_name] [--ovmf ovmf_file_path]
                [--part_info part_info_name] [--enable_trusty] [--intr_monitor param_setting]
+               [--acpidev_pt HID] [--mmiodev_pt MMIO_regions]
                [--vtpm2 sock_path] [--virtio_poll interval] [--mac_seed seed_string]
                [--ptdev_no_reset] [--debugexit]
                [--lapic_pt] <vm>
@@ -86,6 +87,8 @@ options:
        --intr_monitor: enable interrupt storm monitor
             its params: threshold/s,probe-period(s),delay_time(ms),delay_duration(ms),
        --virtio_poll: enable virtio poll mode with poll interval with ns
+       --acpidev_pt: acpi device ID args: HID in ACPI Table
+       --mmiodev_pt: MMIO resources args: physical MMIO regions
        --vtpm2: Virtual TPM2 args: sock_path=$PATH_OF_SWTPM_SOCKET
        --lapic_pt: enable local apic passthrough
        --rtvm: indicate that the guest is rtvm
@@ -104,6 +107,7 @@ Here's an example showing how to run a VM with:
 -  GPU device on PCI 00:02.0
 -  Virtio-block device on PCI 00:03.0
 -  Virtio-net device on PCI 00:04.0
+-  TPM2 MSFT0101
 
 .. code-block:: bash
 
@@ -113,6 +117,7 @@ Here's an example showing how to run a VM with:
      -s 5,virtio-console,@pty:pty_port \
      -s 3,virtio-blk,b,/data/clearlinux/clearlinux.img \
      -s 4,virtio-net,tap_LaaG --vsbl /usr/share/acrn/bios/VSBL.bin \
+     --acpidev_pt MSFT0101 \
      --intr_monitor 10000,10,1,100 \
      -B "root=/dev/vda2 rw rootwait maxcpus=3 nohpet console=hvc0 \
      console=ttyS0 no_timer_check ignore_loglevel log_buf_len=16M \
@@ -1193,4 +1198,5 @@ Passthrough in Device Model
 ****************************
 
 You may refer to :ref:`hv-device-passthrough` for passthrough realization
-in device model.
+in device model and :ref:`mmio-device-passthrough` for MMIO passthrough realization
+in device model and ACRN Hypervisor..
diff --git a/doc/developer-guides/hld/mmio-dev-passthrough.rst b/doc/developer-guides/hld/mmio-dev-passthrough.rst
new file mode 100644
index 000000000..9a18de1cc
--- /dev/null
+++ b/doc/developer-guides/hld/mmio-dev-passthrough.rst
@@ -0,0 +1,40 @@
+.. _mmio-device-passthrough:
+
+MMIO Device Passthrough
+########################
+
+The ACRN Hypervisor supports both PCI and MMIO device passthrough.
+However there are some constraints on and hypervisor assumptions about
+MMIO devices: there can be no DMA access to the MMIO device and the MMIO
+device may not use IRQs.
+
+Here is how ACRN supports MMIO device passthrough:
+
+* For a pre-launched VM, the VM configuration tells the ACRN hypervisor
+  the addresses of the physical MMIO device's regions and where they are
+  mapped to in the pre-launched VM.  The hypervisor then removes these
+  MMIO regions from the Service VM and fills the vACPI table for this MMIO
+  device based on the device's physical ACPI table.
+
+* For a post-launched VM, the same actions are done as in a
+  pre-launched VM, plus we use the command line to tell which MMIO
+  device we want to pass through to the post-launched VM.
+
+  If the MMIO device has ACPI Tables, use ``--acpidev_pt HID`` and
+  if not, use ``--mmiodev_pt MMIO_regions``.
+
+.. note::
+   Currently, the vTPM and PT TPM in the ACRN-DM have the same HID so we
+   can't support them both at the same time. The VM will fail to boot if
+   both are used.
+
+These issues remain to be implemented:
+
+* Save the MMIO regions in a field of the VM structure in order to
+  release the resources when the post-launched VM shuts down abnormally.
+* Allocate the guest MMIO regions for the MMIO device in a guest-reserved
+  MMIO region instead of being hard-coded. With this, we could add more
+  passthrough MMIO devices.
+* De-assign the MMIO device from the Service VM first before passing
+  through it to the post-launched VM and not only removing the MMIO
+  regions from the Service VM.