mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-07-31 23:38:24 +00:00
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:
parent
d68f223dde
commit
40d745b7f8
43
doc/developer-guides/hld/acpi-dev-passthrough.rst
Normal file
43
doc/developer-guides/hld/acpi-dev-passthrough.rst
Normal 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.
|
@ -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.
|
||||
|
@ -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>
|
||||
|
@ -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
|
||||
|
@ -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>``
|
||||
|
Loading…
Reference in New Issue
Block a user