[PATCH docs] qm: pci passthrough: add note for passing through GPUs with large VRAM

[PATCH docs] qm: pci passthrough: add note for passing through GPUs with large VRAM

[Dominik Csapak]

Add it in a new section for common issues. We can reuse that when we
encounter more setups that need more fine-tuning or configuration to work
properly.

This is mostly copied from the wiki[0] but with slight reordering and a
short introductory sentence.

Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
---
 qm-pci-passthrough.adoc | 52 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/qm-pci-passthrough.adoc b/qm-pci-passthrough.adoc
index 8a44a13..ca0ce64 100644
--- a/qm-pci-passthrough.adoc
+++ b/qm-pci-passthrough.adoc
@@ -510,6 +510,58 @@ properly used with HA and hardware changes are detected and non root users
 can configure them. See xref:resource_mapping[Resource Mapping]
 for details on that.
 
+Common Issues
+~~~~~~~~~~~~~
+
+Passing through GPUs with large amount of VRAM with OVMF
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, OVMF reserves only 32 GB of address space for the 64-bit PCI MMIO
+window (see the https://github.com/tianocore/edk2/blob/master/OvmfPkg/RUNTIME_CONFIG.md#platform-optovmfx-pcimmio64mb[edk2 docs]).
+When you pass through a GPU with more than 16 GB of VRAM, that window
+is too small to map the device's memory, and the guest fails to initialize it.
+
+This can surface in different ways depending on the guest OS. Two common examples:
+
+In the guest's kernel journal (Linux):
+
+----
+kernel: nvidia 0000:01:00.0: enabling device (0000 -> 0002)
+kernel: NVRM: This PCI I/O region assigned to your NVIDIA device is invalid:
+        NVRM: BAR0 is 0M @ 0x0 (PCI:0000:01:00.0)
+kernel: nvidia: probe of 0000:01:00.0 failed with error -1
+kernel: NVRM: The NVIDIA probe routine failed for 1 device(s).
+----
+
+In Windows Device Manager:
+
+----
+This device cannot find enough free resources that it can use. (Code 12)
+----
+
+There are multiple possible solutions:
+
+* Use `host` CPU type. This changes the MMIO size calculation for OVMF with
+info from the host CPU.
+* If you can't or don't want to use `host` type CPU, you can set `phys-bits` to
+`host` (or a sufficiently large number). If the necessary bits are greater
+than `40` the flag `pdpe1gb` is also necessary. That flag is included in some
+CPU models but it can be added with (using x86-64-v2-AES as an example):
+
+----
+qm set VMID --cpu x86-64-v2-AES,phys-bits=host,flags=+pdpe1gb
+----
+
+* Should neither of that work, you can manually set the MMIO window size, e.g.
+to 64 GB:
+
+----
+qm set VMID --args '-fw_cfg name=opt/ovmf/X-PciMmio64Mb,string=65536'
+----
+Set it to larger values if necessary, e.g. 131072 for 128GB or 262144 for 256GB.
+
+* Alternatively, SeaBIOS can be used instead of OVMF, which should not cause such issues.
+
 [[qm_pci_viommu]]
 vIOMMU (emulated IOMMU)
 ~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.47.3