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>
This commit is contained in:
yichongt 2024-08-28 15:30:02 +08:00
parent d68f223dde
commit 40d745b7f8
5 changed files with 90 additions and 9 deletions

View File

@ -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.

View File

@ -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.

View File

@ -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>

View File

@ -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

View File

@ -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>``