doc: add ACPI device passthrough section

Add description on ACPI device passthrough and guide on
--acpidev_pt parameter.

Signed-off-by: Yichong Tang <yichong.tang@intel.com>

doc/developer-guides/hld/acpi-dev-passthrough.rst

@@ -0,0 +1,43 @@
+.. _acpi-device-passthrough:
+
+ACPI Device Passthrough
+########################
+
+The ACRN Hypervisor supports ACPI device passthrough with MMIO, PIO and
+IRQ resource.
+
+Here is how ACRN supports ACPI device passthrough:
+
+* Before passthrough, to ensure those ACPI devices not being accessd by
+  Service VM after assigned to post launched VM, launch script should add
+  command to unbind device instance with driver's unbind interface according
+  to capability of different ACPI device drivers before launching VMs.
+  For TPM, UART and GPIO controller, all their drivers provide such unbind
+  interface under sysfs node.
+
+* For MMIO resource, we use the command line to tell the ACRN hypervisor
+  the addresses of physical ACPI device's MMIO regions and where they are
+  mapped to in the post-launched VM. The hypervisor then remove these
+  MMIO regions from the Service VM and fills the vACPI table for this ACPI
+  device.
+
+* For PIO resource, we use the command line to tell the ACRN hypervisor
+  the addresses of physical ACPI device's PIO regions and they will be
+  identically mapped in the post-launched VM. The hypervisor then remove
+  these PIO regions from the Service VM and fills the vACPI table for this
+  ACPI device.
+
+* For IRQ resource, we use the command line to tell the ACRN hypervisor
+  the addresses of physical ACPI device's IRQ numbers and they will be
+  identically mapped in the post-launched VM, as all passthrough-supported
+  ACPI devices use IRQs within number 0-15 whose usage are commonly accepted.
+  The hypervisor then remove these IRQ mapping from Service VM and fills the
+  vACPI table specifying polarity and trigger mode of interrupt as options
+  for this ACPI device.
+
+Supported ACPI devices are TPM, UART and GPIO controller.
+
+.. note::
+   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.

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

@@ -56,7 +56,7 @@ options:
                [-l lpc] [-m mem] [-r ramdisk_image_path]
                [-s pci] [--ovmf ovmf_file_path]
                [--enable_trusty] [--intr_monitor param_setting]
-               [--acpidev_pt HID[,UID]] [--mmiodev_pt MMIO_regions]
+               [--acpidev_pt HID] [--mmiodev_pt MMIO_regions]
                [--vtpm2 sock_path] [--virtio_poll interval] [--mac_seed seed_string]
                [--cpu_affinity lapic_ids] [--lapic_pt] [--rtvm] [--windows]
                [--debugexit] [--logger-setting param_setting]
@@ -75,13 +75,14 @@ options:
        --ovmf: ovmf file path
        --ssram: Enable Software SRAM
        --cpu_affinity: comma-separated of Service VM vCPUs assigned to this VM. A Service VM vCPU is
-            identified by its lapic ID.\n"
+            identified by its lapic ID.
        --enable_trusty: enable trusty for guest
        --debugexit: enable debug exit function
        --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,UID from the ACPI tables
+       --acpidev_pt: ACPI device pass through
+            its params: HID[,uid=UID,type=Resource Type,Resouece config,...]
        --mmiodev_pt: MMIO resources args: physical MMIO regions
        --vtpm2: Virtual TPM2 args: sock_path=$PATH_OF_SWTPM_SOCKET
        --lapic_pt: enable local apic passthrough
@@ -1202,4 +1203,5 @@ Passthrough in Device Model
 
 Refer to :ref:`hv-device-passthrough` for passthrough realization
 in the Device Model and :ref:`mmio-device-passthrough` for MMIO passthrough
+realization and :ref:`acpi-device-passthrough` for ACPI device passthrough
 realization in the Device Model and ACRN hypervisor.

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

@@ -19,6 +19,7 @@ Hypervisor High-Level Design
    VT-d <hv-vt-d>
    Device Passthrough <hv-dev-passthrough>
    mmio-dev-passthrough
+   acpi-dev-passthrough
    hv-partitionmode
    Power Management <hv-pm>
    Console, Shell, and vUART <hv-console>

doc/developer-guides/hld/mmio-dev-passthrough.rst

@@ -23,11 +23,6 @@ Here is how ACRN supports MMIO device passthrough:
   If the MMIO device has ACPI Tables, use ``--acpidev_pt HID[,UID]`` and
   if not, use ``--mmiodev_pt MMIO_regions``.
 
-.. note::
-   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

doc/user-guides/acrn-dm-parameters.rst

@@ -227,7 +227,7 @@ Here are descriptions for each of these ``acrn-dm`` command-line parameters:
 
 ----
 
-``--acpidev_pt <HID>[,<UID>]``
+``--acpidev_pt <HID>[,uid=<UID>,type=<Resource Type>,<Resouece config>,...]``
    Enable ACPI device passthrough support. The ``HID`` is a
    mandatory parameter and is the Hardware ID of the ACPI
    device.
@@ -235,6 +235,25 @@ Here are descriptions for each of these ``acrn-dm`` command-line parameters:
    The ``UID`` is an option and used to specify an instance of the
    HID device, the default is 00.
 
+   The  ``type`` is the type of the ACPI device owned resource.
+   The available options for this parameter are ``irq``, ``memory`` and
+   ``io_port``.
+
+   For different types:
+
+   - ``irq`` require ``irq=<IRQ>`` as mandatory parameter which is the
+     IRQ used by ACPI device. ``polarity=<POLARITY>`` and
+     ``trigger_mode=<TRIGGER_MODE>`` are options to specify interrupt
+     attributes.
+   
+   - ``memory`` require ``min=<MIN>`` and ``len=<LENGTH>`` as mandatory
+     parameter which is the base address and the length of MMIO region of
+     ACPI device.
+   
+   - ``io_port`` require ``min=<MIN>`` and ``len=<LENGTH>`` as mandatory
+     parameter which is the base address and the length of PIO region of
+     ACPI device.
+
    Example::
 
       --acpidev_pt MSFT0101,00
@@ -242,6 +261,27 @@ Here are descriptions for each of these ``acrn-dm`` command-line parameters:
    to pass through a TPM (HID is MSFT0101 and UID is 00) ACPI device to
    a User VM.
 
+   ::
+
+      --acpidev_pt PNP0501,uid=19,type=io_port,min=0x2f8,len=8
+      --acpidev_pt PNP0501,uid=19,type=irq,irq=3
+   
+   to pass through a UART (HID is PNP0501 and UID is 19) ACPI device to
+   a User VM, with PIO region of base address 0x2F8 and length 8, and IRQ
+   of number 3.
+
+   ::
+
+      --acpidev_pt INTC1055,type=irq,irq=14,polarity=3,trigger_mode=3
+      --acpidev_pt INTC1055,type=memory,min=0xfd6e0000,len=0x10000
+      --acpidev_pt INTC1055,type=memory,min=0xfd6d0000,len=0x10000
+      --acpidev_pt INTC1055,type=memory,min=0xfd6a0000,len=0x10000
+      --acpidev_pt INTC1055,type=memory,min=0xfd690000,len=0x10000
+   
+   to pass through a GPIO controller (HID is INTC1055 and UID is 00) ACPI
+   device to a User VM, with its four MMIO regions and IRQ which specifes
+   polarity and trigger mode.
+
 ----
 
 ``--mmiodev_pt <MMIO_Region>``