1.. _gpu-passthrough: 2 3Enable GPU Passthrough (GVT-d) 4############################## 5 6About GVT-d 7************ 8 9GVT-d is a graphics virtualization approach that is also known as the 10Intel-Graphics-Device passthrough feature. It allows for direct assignment of a 11GPU to a single VM, passing the native driver capabilities through to the 12hypervisor without any limitations. For example, you can pass through a VGA 13controller to a VM, allowing users to access a Windows or Ubuntu desktop. 14 15A typical use of GVT-d is to give a post-launched VM full control to the 16graphics card when that VM serves as the main user interface while all the other 17VMs are in the background and headless. 18 19Dependencies and Constraints 20**************************** 21 22Consider the following dependencies and constraints: 23 24* GVT-d applies only to an Intel integrated graphics card. Discrete graphics 25 cards are passed through to VMs as a standard PCI device. 26 27* When a device is assigned to a VM via GVT-d, no other VMs can use it. 28 29* For ASRock systems, disable the BIOS setting "Above 4G Decoding" (under 30 Advanced Menu > SA Configuration) to enable the GVT-d feature. 31 32.. note:: After GVT-d is enabled, have either a serial port 33 or SSH session open in the Service VM to interact with it. 34 35Configuration Overview 36********************** 37 38The :ref:`acrn_configurator_tool` lets you select PCI devices, such as VGA 39controllers, as passthrough devices for a VM. The following documentation is a 40general overview of the configuration process. 41 42To select a passthrough device for a VM, select the VM and go to **Basic 43Parameters > PCI devices**. Click **+** to add a device. 44 45.. image:: images/configurator-gvtd02.png 46 :align: center 47 :class: drop-shadow 48 49Select the device from the list. 50 51.. image:: images/configurator-gvtd01.png 52 :align: center 53 :class: drop-shadow 54 55To add another passthrough device, click **+**. Or click **x** to delete a 56device. 57 58Example Configuration 59********************* 60 61The following steps show how to select and verify a passthrough VGA controller. 62The example extends the information provided in the :ref:`gsg`. 63 64#. In the ACRN Configurator, create a shared scenario with a Service VM and one 65 post-launched User VM. 66 67#. Select the Service VM and go to **Basic Parameters > Kernel 68 command-line parameters**. 69 70#. Append ``i915.modeset=0`` in **Kernel command-line parameters** to disable the 71 GPU driver loading for Intel GPU device. 72 73 .. image:: images/kernel_cmd_line.png 74 :align: center 75 :class: drop-shadow 76 77#. Select the post-launched User VM and go to **Basic Parameters > PCI 78 devices**. 79 80#. Click **+** to add a device, and select the VGA controller. 81 82 .. image:: images/configurator-gvtd01.png 83 :align: center 84 :class: drop-shadow 85 86#. Save the scenario and launch script. 87 88#. Build ACRN, copy all the necessary files from the development computer to the 89 target system, and launch the Service VM and post-launched User VM. 90 91#. Verify that the VM can access the VGA controller: Run the following command 92 in the post-launched User VM: 93 94 .. code-block:: console 95 96 root@acrn-Standard-PC-i440FX-PIIX-1996:~# lspci |grep VGA 97 00:02.0 VGA compatible controller: Intel Corporation Device 4680 (rev 0c) 98 99Troubleshooting 100*************** 101 102Enable the GVT-d GOP Driver 103=========================== 104 105When enabling GVT-d, the Guest OS cannot light up the physical screen 106before the OS driver loads. As a result, the Guest BIOS and the Grub UI 107are not visible on the physical screen. This occurs because the physical 108display is initialized by the GOP driver or VBIOS before the OS driver 109loads, and the Guest BIOS doesn't have them. 110 111The solution is to integrate the GOP driver binary into the OVMF as a DXE 112driver. Then the Guest OVMF can see the GOP driver and run it in the graphic 113passthrough environment. The physical display can be initialized 114by the GOP and used by the Guest BIOS and Guest Grub. 115 116Steps 117----- 118 1191. Fetch the ACRN OVMF: 120 121 :: 122 123 git clone https://github.com/projectacrn/acrn-edk2.git 124 125#. Fetch the VBT and GOP drivers. 126 127 Fetch the **VBT** and **GOP** drivers from the board manufacturer 128 according to your CPU model name. 129 130#. Add the **VBT** and **GOP** drivers to the OVMF: 131 132 :: 133 134 cp IntelGopDriver.efi acrn-edk2/OvmfPkg/IntelGop/IntelGopDriver.efi 135 cp Vbt.bin acrn-edk2/OvmfPkg/Vbt/Vbt.bin 136 137 Confirm that these binaries names match the board manufacturer names. 138 139#. Use ``git apply`` to add the following two patches: 140 141 * `Use-the-default-vbt-released-with-GOP-driver.patch <../_static/downloads/Use-the-default-vbt-released-with-GOP-driver.patch>`_ 142 143 * `Integrate-IntelGopDriver-into-OVMF.patch <../_static/downloads/Integrate-IntelGopDriver-into-OVMF.patch>`_ 144 145#. Compile the OVMF: 146 147 :: 148 149 cd acrn-edk2 150 git submodule update --init CryptoPkg/Library/OpensslLib/openssl 151 152 source edksetup.sh 153 make -C BaseTools 154 155 vim Conf/target.txt 156 157 ACTIVE_PLATFORM = OvmfPkg/OvmfPkgX64.dsc 158 TARGET_ARCH = X64 159 TOOL_CHAIN_TAG = GCC5 160 161 build -DFD_SIZE_2MB -DDEBUG_ON_SERIAL_PORT=TRUE 162 163Keep in mind the following: 164 165 - Use a build machine that has GCC 5.X version installed. 166 167 - The ``source edksetup.sh`` step is needed for compilation every time 168 a shell is created. 169 170 - This will generate the binary at 171 ``Build/OvmfX64/DEBUG_GCC5/FV/OVMF.fd``. Transfer the binary to 172 your target machine. 173 - Modify the launch script to specify the OVMF you built just now. 174 175Script 176------ 177 178Once you've installed the Docker environment, you can use this 179`script <../_static/downloads/build_acrn_ovmf.sh>`_ to build ACRN OVMF 180with the GOP driver enabled. For more details about the script usage, 181run ``build_acrn_ovmf.sh -h``. 182
