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