From 40d745b7f84ddee114599695e8d6ecc14d221c29 Mon Sep 17 00:00:00 2001 From: yichongt Date: Wed, 28 Aug 2024 15:30:02 +0800 Subject: [PATCH] doc: add ACPI device passthrough section Add description on ACPI device passthrough and guide on --acpidev_pt parameter. Signed-off-by: Yichong Tang --- .../hld/acpi-dev-passthrough.rst | 43 +++++++++++++++++++ doc/developer-guides/hld/hld-devicemodel.rst | 8 ++-- doc/developer-guides/hld/hld-hypervisor.rst | 1 + .../hld/mmio-dev-passthrough.rst | 5 --- doc/user-guides/acrn-dm-parameters.rst | 42 +++++++++++++++++- 5 files changed, 90 insertions(+), 9 deletions(-) create mode 100644 doc/developer-guides/hld/acpi-dev-passthrough.rst diff --git a/doc/developer-guides/hld/acpi-dev-passthrough.rst b/doc/developer-guides/hld/acpi-dev-passthrough.rst new file mode 100644 index 0000000000..5514650e14 --- /dev/null +++ b/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. diff --git a/doc/developer-guides/hld/hld-devicemodel.rst b/doc/developer-guides/hld/hld-devicemodel.rst index 1fcd52d2db..d631cf3372 100644 --- a/doc/developer-guides/hld/hld-devicemodel.rst +++ b/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. diff --git a/doc/developer-guides/hld/hld-hypervisor.rst b/doc/developer-guides/hld/hld-hypervisor.rst index 276c4f3018..6f61544f6c 100644 --- a/doc/developer-guides/hld/hld-hypervisor.rst +++ b/doc/developer-guides/hld/hld-hypervisor.rst @@ -19,6 +19,7 @@ Hypervisor High-Level Design VT-d Device Passthrough mmio-dev-passthrough + acpi-dev-passthrough hv-partitionmode Power Management Console, Shell, and vUART diff --git a/doc/developer-guides/hld/mmio-dev-passthrough.rst b/doc/developer-guides/hld/mmio-dev-passthrough.rst index 9b5f4b81fe..e2e4c06bbe 100644 --- a/doc/developer-guides/hld/mmio-dev-passthrough.rst +++ b/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 diff --git a/doc/user-guides/acrn-dm-parameters.rst b/doc/user-guides/acrn-dm-parameters.rst index d4e305b871..23ce3bbf50 100755 --- a/doc/user-guides/acrn-dm-parameters.rst +++ b/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 [,]`` +``--acpidev_pt [,uid=,type=,,...]`` 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=`` as mandatory parameter which is the + IRQ used by ACPI device. ``polarity=`` and + ``trigger_mode=`` are options to specify interrupt + attributes. + + - ``memory`` require ``min=`` and ``len=`` as mandatory + parameter which is the base address and the length of MMIO region of + ACPI device. + + - ``io_port`` require ``min=`` and ``len=`` 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 ``