182 lines
5.6 KiB
ReStructuredText
182 lines
5.6 KiB
ReStructuredText
.. _gpu-passthrough:
|
|
|
|
Enable GPU Passthrough (GVT-d)
|
|
##############################
|
|
|
|
About GVT-d
|
|
************
|
|
|
|
GVT-d is a graphics virtualization approach that is also known as the
|
|
Intel-Graphics-Device passthrough feature. It allows for direct assignment of a
|
|
GPU to a single VM, passing the native driver capabilities through to the
|
|
hypervisor without any limitations. For example, you can pass through a VGA
|
|
controller to a VM, allowing users to access a Windows or Ubuntu desktop.
|
|
|
|
A typical use of GVT-d is to give a post-launched VM full control to the
|
|
graphics card when that VM serves as the main user interface while all the other
|
|
VMs are in the background and headless.
|
|
|
|
Dependencies and Constraints
|
|
****************************
|
|
|
|
Consider the following dependencies and constraints:
|
|
|
|
* GVT-d applies only to an Intel integrated graphics card. Discrete graphics
|
|
cards are passed through to VMs as a standard PCI device.
|
|
|
|
* When a device is assigned to a VM via GVT-d, no other VMs can use it.
|
|
|
|
* For ASRock systems, disable the BIOS setting "Above 4G Decoding" (under
|
|
Advanced Menu > SA Configuration) to enable the GVT-d feature.
|
|
|
|
.. note:: After GVT-d is enabled, have either a serial port
|
|
or SSH session open in the Service VM to interact with it.
|
|
|
|
Configuration Overview
|
|
**********************
|
|
|
|
The :ref:`acrn_configurator_tool` lets you select PCI devices, such as VGA
|
|
controllers, as passthrough devices for a VM. The following documentation is a
|
|
general overview of the configuration process.
|
|
|
|
To select a passthrough device for a VM, select the VM and go to **Basic
|
|
Parameters > PCI devices**. Click **+** to add a device.
|
|
|
|
.. image:: images/configurator-gvtd02.png
|
|
:align: center
|
|
:class: drop-shadow
|
|
|
|
Select the device from the list.
|
|
|
|
.. image:: images/configurator-gvtd01.png
|
|
:align: center
|
|
:class: drop-shadow
|
|
|
|
To add another passthrough device, click **+**. Or click **x** to delete a
|
|
device.
|
|
|
|
Example Configuration
|
|
*********************
|
|
|
|
The following steps show how to select and verify a passthrough VGA controller.
|
|
The example extends the information provided in the :ref:`gsg`.
|
|
|
|
#. In the ACRN Configurator, create a shared scenario with a Service VM and one
|
|
post-launched User VM.
|
|
|
|
#. Select the Service VM and go to **Basic Parameters > Kernel
|
|
command-line parameters**.
|
|
|
|
#. Append ``i915.modeset=0`` in **Kernel command-line parameters** to disable the
|
|
GPU driver loading for Intel GPU device.
|
|
|
|
.. image:: images/kernel_cmd_line.png
|
|
:align: center
|
|
:class: drop-shadow
|
|
|
|
#. Select the post-launched User VM and go to **Basic Parameters > PCI
|
|
devices**.
|
|
|
|
#. Click **+** to add a device, and select the VGA controller.
|
|
|
|
.. image:: images/configurator-gvtd01.png
|
|
:align: center
|
|
:class: drop-shadow
|
|
|
|
#. Save the scenario and launch script.
|
|
|
|
#. Build ACRN, copy all the necessary files from the development computer to the
|
|
target system, and launch the Service VM and post-launched User VM.
|
|
|
|
#. Verify that the VM can access the VGA controller: Run the following command
|
|
in the post-launched User VM:
|
|
|
|
.. code-block:: console
|
|
|
|
root@acrn-Standard-PC-i440FX-PIIX-1996:~# lspci |grep VGA
|
|
00:02.0 VGA compatible controller: Intel Corporation Device 4680 (rev 0c)
|
|
|
|
Troubleshooting
|
|
***************
|
|
|
|
Enable the GVT-d GOP Driver
|
|
===========================
|
|
|
|
When enabling GVT-d, the Guest OS cannot light up the physical screen
|
|
before the OS driver loads. As a result, the Guest BIOS and the Grub UI
|
|
are not visible on the physical screen. This occurs because the physical
|
|
display is initialized by the GOP driver or VBIOS before the OS driver
|
|
loads, and the Guest BIOS doesn't have them.
|
|
|
|
The solution is to integrate the GOP driver binary into the OVMF as a DXE
|
|
driver. Then the Guest OVMF can see the GOP driver and run it in the graphic
|
|
passthrough environment. The physical display can be initialized
|
|
by the GOP and used by the Guest BIOS and Guest Grub.
|
|
|
|
Steps
|
|
-----
|
|
|
|
1. Fetch the ACRN OVMF:
|
|
|
|
::
|
|
|
|
git clone https://github.com/projectacrn/acrn-edk2.git
|
|
|
|
#. Fetch the VBT and GOP drivers.
|
|
|
|
Fetch the **VBT** and **GOP** drivers from the board manufacturer
|
|
according to your CPU model name.
|
|
|
|
#. Add the **VBT** and **GOP** drivers to the OVMF:
|
|
|
|
::
|
|
|
|
cp IntelGopDriver.efi acrn-edk2/OvmfPkg/IntelGop/IntelGopDriver.efi
|
|
cp Vbt.bin acrn-edk2/OvmfPkg/Vbt/Vbt.bin
|
|
|
|
Confirm that these binaries names match the board manufacturer names.
|
|
|
|
#. Use ``git apply`` to add the following two patches:
|
|
|
|
* `Use-the-default-vbt-released-with-GOP-driver.patch <../_static/downloads/Use-the-default-vbt-released-with-GOP-driver.patch>`_
|
|
|
|
* `Integrate-IntelGopDriver-into-OVMF.patch <../_static/downloads/Integrate-IntelGopDriver-into-OVMF.patch>`_
|
|
|
|
#. Compile the OVMF:
|
|
|
|
::
|
|
|
|
cd acrn-edk2
|
|
git submodule update --init CryptoPkg/Library/OpensslLib/openssl
|
|
|
|
source edksetup.sh
|
|
make -C BaseTools
|
|
|
|
vim Conf/target.txt
|
|
|
|
ACTIVE_PLATFORM = OvmfPkg/OvmfPkgX64.dsc
|
|
TARGET_ARCH = X64
|
|
TOOL_CHAIN_TAG = GCC5
|
|
|
|
build -DFD_SIZE_2MB -DDEBUG_ON_SERIAL_PORT=TRUE
|
|
|
|
Keep in mind the following:
|
|
|
|
- Use a build machine that has GCC 5.X version installed.
|
|
|
|
- The ``source edksetup.sh`` step is needed for compilation every time
|
|
a shell is created.
|
|
|
|
- This will generate the binary at
|
|
``Build/OvmfX64/DEBUG_GCC5/FV/OVMF.fd``. Transfer the binary to
|
|
your target machine.
|
|
- Modify the launch script to specify the OVMF you built just now.
|
|
|
|
Script
|
|
------
|
|
|
|
Once you've installed the Docker environment, you can use this
|
|
`script <../_static/downloads/build_acrn_ovmf.sh>`_ to build ACRN OVMF
|
|
with the GOP driver enabled. For more details about the script usage,
|
|
run ``build_acrn_ovmf.sh -h``.
|