pvecm: whitespace fixup
[pve-docs.git] / qm-pci-passthrough.adoc
1 [[qm_pci_passthrough]]
2 PCI(e) Passthrough
3 ------------------
4 ifdef::wiki[]
5 :pve-toplevel:
6 endif::wiki[]
7
8 PCI(e) passthrough is a mechanism to give a virtual machine control over
9 a PCI device from the host. This can have some advantages over using
10 virtualized hardware, for example lower latency, higher performance, or more
11 features (e.g., offloading).
12
13 But, if you pass through a device to a virtual machine, you cannot use that
14 device anymore on the host or in any other VM.
15
16 General Requirements
17 ~~~~~~~~~~~~~~~~~~~~
18
19 Since passthrough is a feature which also needs hardware support, there are
20 some requirements to check and preparations to be done to make it work.
21
22
23 Hardware
24 ^^^^^^^^
25 Your hardware needs to support `IOMMU` (*I*/*O* **M**emory **M**anagement
26 **U**nit) interrupt remapping, this includes the CPU and the mainboard.
27
28 Generally, Intel systems with VT-d, and AMD systems with AMD-Vi support this.
29 But it is not guaranteed that everything will work out of the box, due
30 to bad hardware implementation and missing or low quality drivers.
31
32 Further, server grade hardware has often better support than consumer grade
33 hardware, but even then, many modern system can support this.
34
35 Please refer to your hardware vendor to check if they support this feature
36 under Linux for your specific setup.
37
38
39 Configuration
40 ^^^^^^^^^^^^^
41
42 Once you ensured that your hardware supports passthrough, you will need to do
43 some configuration to enable PCI(e) passthrough.
44
45
46 .IOMMU
47
48 The IOMMU has to be activated on the
49 xref:sysboot_edit_kernel_cmdline[kernel commandline].
50
51 The command line parameters are:
52
53 * for Intel CPUs:
54 +
55 ----
56  intel_iommu=on
57 ----
58 * for AMD CPUs:
59 +
60 ----
61  amd_iommu=on
62 ----
63
64
65 .Kernel Modules
66
67 You have to make sure the following modules are loaded. This can be achieved by
68 adding them to `'/etc/modules''
69
70 ----
71  vfio
72  vfio_iommu_type1
73  vfio_pci
74  vfio_virqfd
75 ----
76
77 [[qm_pci_passthrough_update_initramfs]]
78 After changing anything modules related, you need to refresh your
79 `initramfs`. On {pve} this can be done by executing:
80
81 ----
82 # update-initramfs -u -k all
83 ----
84
85 .Finish Configuration
86
87 Finally reboot to bring the changes into effect and check that it is indeed
88 enabled.
89
90 ----
91 # dmesg | grep -e DMAR -e IOMMU -e AMD-Vi
92 ----
93
94 should display that `IOMMU`, `Directed I/O` or `Interrupt Remapping` is
95 enabled, depending on hardware and kernel the exact message can vary.
96
97 It is also important that the device(s) you want to pass through
98 are in a *separate* `IOMMU` group. This can be checked with:
99
100 ----
101 # find /sys/kernel/iommu_groups/ -type l
102 ----
103
104 It is okay if the device is in an `IOMMU` group together with its functions
105 (e.g. a GPU with the HDMI Audio device) or with its root port or PCI(e) bridge.
106
107 .PCI(e) slots
108 [NOTE]
109 ====
110 Some platforms handle their physical PCI(e) slots differently. So, sometimes
111 it can help to put the card in a another PCI(e) slot, if you do not get the
112 desired `IOMMU` group separation.
113 ====
114
115 .Unsafe interrupts
116 [NOTE]
117 ====
118 For some platforms, it may be necessary to allow unsafe interrupts.
119 For this add  the following line in a file ending with `.conf' file in
120 */etc/modprobe.d/*:
121
122 ----
123  options vfio_iommu_type1 allow_unsafe_interrupts=1
124 ----
125
126 Please be aware that this option can make your system unstable.
127 ====
128
129 GPU Passthrough Notes
130 ^^^^^^^^^^^^^^^^^^^^^
131
132 It is not possible to display the frame buffer of the GPU via NoVNC or SPICE on
133 the {pve} web interface.
134
135 When passing through a whole GPU or a vGPU and graphic output is wanted, one
136 has to either physically connect a monitor to the card, or configure a remote
137 desktop software (for example, VNC or RDP) inside the guest.
138
139 If you want to use the GPU as a hardware accelerator, for example, for
140 programs using OpenCL or CUDA, this is not required.
141
142 Host Device Passthrough
143 ~~~~~~~~~~~~~~~~~~~~~~~
144
145 The most used variant of PCI(e) passthrough is to pass through a whole
146 PCI(e) card, for example a GPU or a network card.
147
148
149 Host Configuration
150 ^^^^^^^^^^^^^^^^^^
151
152 In this case, the host must not use the card. There are two methods to achieve
153 this:
154
155 * pass the device IDs to the options of the 'vfio-pci' modules by adding
156 +
157 ----
158  options vfio-pci ids=1234:5678,4321:8765
159 ----
160 +
161 to a .conf file in */etc/modprobe.d/* where `1234:5678` and `4321:8765` are
162 the vendor and device IDs obtained by:
163 +
164 ----
165 # lspci -nn
166 ----
167
168 * blacklist the driver completely on the host, ensuring that it is free to bind
169 for passthrough, with
170 +
171 ----
172  blacklist DRIVERNAME
173 ----
174 +
175 in a .conf file in */etc/modprobe.d/*.
176
177 For both methods you need to
178 xref:qm_pci_passthrough_update_initramfs[update the `initramfs`] again and
179 reboot after that.
180
181 .Verify Configuration
182
183 To check if your changes were successful, you can use
184
185 ----
186 # lspci -nnk
187 ----
188
189 and check your device entry. If it says
190
191 ----
192 Kernel driver in use: vfio-pci
193 ----
194
195 or the 'in use' line is missing entirely, the device is ready to be used for
196 passthrough.
197
198 [[qm_pci_passthrough_vm_config]]
199 VM Configuration
200 ^^^^^^^^^^^^^^^^
201 To pass through the device you need to set the *hostpciX* option in the VM
202 configuration, for example by executing:
203
204 ----
205 # qm set VMID -hostpci0 00:02.0
206 ----
207
208 If your device has multiple functions (e.g., ``00:02.0`' and ``00:02.1`' ),
209 you can pass them through all together with the shortened syntax ``00:02`'
210
211 There are some options to which may be necessary, depending on the device
212 and guest OS:
213
214 * *x-vga=on|off* marks the PCI(e) device as the primary GPU of the VM.
215 With this enabled the *vga* configuration option will be ignored.
216
217 * *pcie=on|off* tells {pve} to use a PCIe or PCI port. Some guests/device
218 combination require PCIe rather than PCI. PCIe is only available for 'q35'
219 machine types.
220
221 * *rombar=on|off* makes the firmware ROM visible for the guest. Default is on.
222 Some PCI(e) devices need this disabled.
223
224 * *romfile=<path>*, is an optional path to a ROM file for the device to use.
225 This is a relative path under */usr/share/kvm/*.
226
227 .Example
228
229 An example of PCIe passthrough with a GPU set to primary:
230
231 ----
232 # qm set VMID -hostpci0 02:00,pcie=on,x-vga=on
233 ----
234
235
236 Other considerations
237 ^^^^^^^^^^^^^^^^^^^^
238
239 When passing through a GPU, the best compatibility is reached when using
240 'q35' as machine type, 'OVMF' ('EFI' for VMs) instead of SeaBIOS and PCIe
241 instead of PCI. Note that if you want to use 'OVMF' for GPU passthrough, the
242 GPU needs to have an EFI capable ROM, otherwise use SeaBIOS instead.
243
244 SR-IOV
245 ~~~~~~
246
247 Another variant for passing through PCI(e) devices, is to use the hardware
248 virtualization features of your devices, if available.
249
250 'SR-IOV' (**S**ingle-**R**oot **I**nput/**O**utput **V**irtualization) enables
251 a single device to provide multiple 'VF' (**V**irtual **F**unctions) to the
252 system. Each of those 'VF' can be used in a different VM, with full hardware
253 features and also better performance and lower latency than software
254 virtualized devices.
255
256 Currently, the most common use case for this are NICs (**N**etwork
257 **I**nterface **C**ard) with SR-IOV support, which can provide multiple VFs per
258 physical port. This allows using features such as checksum offloading, etc. to
259 be used inside a VM, reducing the (host) CPU overhead.
260
261
262 Host Configuration
263 ^^^^^^^^^^^^^^^^^^
264
265 Generally, there are two methods for enabling virtual functions on a device.
266
267 * sometimes there is an option for the driver module e.g. for some
268 Intel drivers
269 +
270 ----
271  max_vfs=4
272 ----
273 +
274 which could be put file with '.conf' ending under */etc/modprobe.d/*.
275 (Do not forget to update your initramfs after that)
276 +
277 Please refer to your driver module documentation for the exact
278 parameters and options.
279
280 * The second, more generic, approach is using the `sysfs`.
281 If a device and driver supports this you can change the number of VFs on
282 the fly. For example, to setup 4 VFs on device 0000:01:00.0 execute:
283 +
284 ----
285 # echo 4 > /sys/bus/pci/devices/0000:01:00.0/sriov_numvfs
286 ----
287 +
288 To make this change persistent you can use the `sysfsutils` Debian package.
289 After installation configure it via */etc/sysfs.conf* or a `FILE.conf' in
290 */etc/sysfs.d/*.
291
292 VM Configuration
293 ^^^^^^^^^^^^^^^^
294
295 After creating VFs, you should see them as separate PCI(e) devices when
296 outputting them with `lspci`. Get their ID and pass them through like a
297 xref:qm_pci_passthrough_vm_config[normal PCI(e) device].
298
299 Other considerations
300 ^^^^^^^^^^^^^^^^^^^^
301
302 For this feature, platform support is especially important. It may be necessary
303 to enable this feature in the BIOS/EFI first, or to use a specific PCI(e) port
304 for it to work. In doubt, consult the manual of the platform or contact its
305 vendor.
306
307 Mediated Devices (vGPU, GVT-g)
308 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
309
310 Mediated devices are another method to reuse features and performance from
311 physical hardware for virtualized hardware. These are found most common in
312 virtualized GPU setups such as Intels GVT-g and Nvidias vGPUs used in their
313 GRID technology.
314
315 With this, a physical Card is able to create virtual cards, similar to SR-IOV.
316 The difference is that mediated devices do not appear as PCI(e) devices in the
317 host, and are such only suited for using in virtual machines.
318
319
320 Host Configuration
321 ^^^^^^^^^^^^^^^^^^
322
323 In general your card's driver must support that feature, otherwise it will
324 not work. So please refer to your vendor for compatible drivers and how to
325 configure them.
326
327 Intels drivers for GVT-g are integrated in the Kernel and should work
328 with 5th, 6th and 7th generation Intel Core Processors, as well as E3 v4, E3
329 v5 and E3 v6 Xeon Processors.
330
331 To enable it for Intel Graphics, you have to make sure to load the module
332 'kvmgt' (for example via `/etc/modules`) and to enable it on the
333 xref:sysboot_edit_kernel_cmdline[Kernel commandline] and add the following parameter:
334
335 ----
336  i915.enable_gvt=1
337 ----
338
339 After that remember to
340 xref:qm_pci_passthrough_update_initramfs[update the `initramfs`],
341 and reboot your host.
342
343 VM Configuration
344 ^^^^^^^^^^^^^^^^
345
346 To use a mediated device, simply specify the `mdev` property on a `hostpciX`
347 VM configuration option.
348
349 You can get the supported devices via the 'sysfs'. For example, to list the
350 supported types for the device '0000:00:02.0' you would simply execute:
351
352 ----
353 # ls /sys/bus/pci/devices/0000:00:02.0/mdev_supported_types
354 ----
355
356 Each entry is a directory which contains the following important files:
357
358 * 'available_instances' contains the amount of still available instances of
359 this type, each 'mdev' use in a VM reduces this.
360 * 'description' contains a short description about the capabilities of the type
361 * 'create' is the endpoint to create such a device, {pve} does this
362 automatically for you, if a 'hostpciX' option with `mdev` is configured.
363
364 Example configuration with an `Intel GVT-g vGPU` (`Intel Skylake 6700k`):
365
366 ----
367 # qm set VMID -hostpci0 00:02.0,mdev=i915-GVTg_V5_4
368 ----
369
370 With this set, {pve} automatically creates such a device on VM start, and
371 cleans it up again when the VM stops.
372
373 ifdef::wiki[]
374
375 See Also
376 ~~~~~~~~
377
378 * link:/wiki/Pci_passthrough[PCI Passthrough Examples]
379
380 endif::wiki[]