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