"title":"Aggiungi GPU a VM | Documentazione ProxMenux",
"description":"Assegna una GPU fisica a una VM Proxmox. ProxMenux verifica IOMMU, configura VFIO e dispositivi VM e rileva conflitti con altre VM o LXC."
},
"header":{
"title":"Aggiungi GPU a VM (Passthrough)",
"description":"Rileva GPU Intel, AMD o NVIDIA per l’accesso diretto da una VM. Verifica IOMMU e dispositivi associati, configura VFIO e VM e applica le regole di compatibilità. Controlla tutti i dispositivi interessati.",
"section":"Hardware: GPU e Coral-TPU"
},
"intro":{
"title":"Cosa fa",
"body":"Automatizza i passaggi host e <code>hostpci</code> della <pveLink>documentazione PCI passthrough Proxmox</pveLink>. Controlla assegnazioni ad <em>altri</em> guest e propone soluzioni ai conflitti. Non garantisce supporto per ogni GPU, metodo di reset o driver guest."
},
"who":{
"heading":"Per chi è questo?",
"body":"Per l’accesso diretto di una <strong>macchina virtuale</strong> alla GPU tramite VFIO. Finché è associata a VFIO, il driver host non può usarla, anche con VM ferma. Per condividerla con <em>LXC</em>, usa <lxcLink>Aggiungi GPU a LXC</lxcLink>."
},
"prereqs":{
"title":"Prima di iniziare",
"gpu":"<strong>GPU compatibile</strong> installata fisicamente. Lo script rileva Intel, AMD e NVIDIA con <code>lspci</code>.",
"gpuCheck":"lspci | grep -iE 'VGA|3D|Display'",
"iommu":"<strong>Supporto IOMMU</strong> hardware e attivazione firmware se richiesta (Intel VT-d o AMD-Vi). Verifica il sistema e può configurare Linux; non cambia BIOS/UEFI né prova che IOMMU inattivo sia disabilitato nel firmware.",
"q35":"L’assistente richiede <strong>q35</strong> e rifiuta <code>i440fx</code>. Il tipo di macchina è distinto dal firmware BIOS/UEFI. Cambiare chipset a una VM esistente richiede pianificazione e non è automatico.",
"q35Check":"qm config VMID | grep machine",
"moreGpus":"Prepara <strong>un’altra GPU o accesso alternativo</strong> via SSH, IPMI o seriale. Riservare la GPU principale può togliere l’immagine locale. Per <em>NVIDIA</em>, una scheda fuori dal gruppo IOMMU interessato può restare sull’host.",
"nvidiaInstalled":"Dopo l’<nvidiaLink>installazione NVIDIA sull’host</nvidiaLink>, le funzioni scelte sono riservate a <code>vfio-pci</code> anziché <code>nvidia</code>. Il modulo <code>nvidia</code> può restare disponibile per <strong>altre</strong> schede fuori dal gruppo IOMMU interessato. Verifica con <code>nvidia-smi</code>."
},
"pickOne":{
"title":"Assegnazione esclusiva VM o condivisione LXC",
"body":"Un GPU legato a <code>vfio-pci</code> per il passaggio VM non può essere utilizzato simultaneamente dall'host o da un LXC. Se hai due GPU, puoi dedicarne uno ad ogni percorso. Se ne hai uno solo, scegli:",
"vmItem":"<strong>VM:</strong> accesso diretto ed esclusivo per quella VM.",
"lxcItem":"<strong>LXC (<lxcLink>Aggiungi GPU a LXC</lxcLink>):</strong> condivide il dispositivo con host e altri container tramite il driver nativo."
},
"running":{
"heading":"Eseguire l’installer",
"body":"Apri ProxMenux e scegli <strong>Hardware: GPU e Coral-TPU → Aggiungi GPU a VM</strong>.",
"imageAlt":"Voce del menu per aggiungere GPU a VM"
},
"howRuns":{
"heading":"Come funziona lo script",
"body":"Rilevamento e selezione precedono le modifiche principali, confermate da un riepilogo finale. Attivare IOMMU ha una conferma precedente e può già modificare l’avvio. La successiva pulizia audio può chiedere un’altra scelta."
"body":"Considera IOMMU attivo solo quando il kernel in esecuzione ha <code>intel_iommu=on</code> o <code>amd_iommu=on</code> ed esistono gruppi IOMMU. Se il parametro è già salvato per il prossimo avvio, prosegue in modalità riavvio in sospeso; altrimenti un passaggio confermato separatamente può aggiungerlo con <code>iommu=pt</code>. La sua euristica per il file di avvio usa <code>/etc/kernel/cmdline</code> quando vi si trova un marcatore di root ZFS come <code>root=ZFS=</code>; altrimenti usa <code>/etc/default/grub</code>. Questa euristica non prova quale sia il bootloader effettivo. L’IOMMU appena configurato ha effetto dopo il riavvio; verifica poi i gruppi reali.",
"tipTitle":"Hai già configurato la post-installazione?",
"tipBody":"Se il <postLink>supporto VFIO IOMMU</postLink> è già configurato e attivo nel kernel, il controllo passa. Un’impostazione per il prossimo avvio non prova che sia attivo ora.",
"imageAlt":"Elenco delle GPU rilevate con indirizzo fornitore e PCI"
},
"preflight":{
"title":"Scegli GPU ed esegui i controlli preliminari",
"intro":"Una volta scelto il GPU, lo script esegue una serie di controlli che possono ogni blocco ulteriori progressi:",
"items":[
"<strong>Controllo SR-IOV.</strong> Rifiuta VF e PF con VF attive perché configura dispositivi interi, non SR-IOV. Configura SR-IOV separatamente su hardware supportato.",
"<strong>Una sola GPU.</strong> La console locale può perdere l’uscita quando VFIO la riserva. Verifica prima l’accesso SSH o web da un altro computer.",
"<strong>Politica di reset AMD.</strong> Legge <code>/sys/bus/pci/devices/<pci>/reset_method</code>. APU o scheda dedicata senza FLR viene <em>bloccata dalla politica dell’assistente</em>; un sottotipo sconosciuto senza FLR richiede conferma. Non prova un’impossibilità universale.",
"<strong>Stato D3cold.</strong> Blocca schede AMD che indicano <code>D3cold</code> per il rischio di mancata attivazione. Verifica alimentazione e firmware.",
"<strong>Analisi del gruppo IOMMU.</strong> Legge <code>/sys/kernel/iommu_groups/</code> e include nel piano della VM <em>tutti i membri non bridge</em>, eventualmente controller di rete o di archiviazione. Se il gruppo contiene dispositivi di un altro slot, lo script li elenca prima del riepilogo; verifica che l’host non ne abbia bisogno. Se IOMMU attende un riavvio, i gruppi reali non sono disponibili e il piano contiene inizialmente solo la funzione GPU selezionata; verifica l’isolamento dopo il riavvio."
"audioIntro":"<strong>Audio associato.</strong> Due casi secondo la posizione del controller:",
"audioDgpu":"<strong>GPU dedicata:</strong> l’audio HDMI occupa spesso la funzione <code>.1</code> dello stesso slot PCI ed è incluso se rilevato. Se l’host lo usava, perde l’accesso riservandolo alla VM.",
"audioIgpu":"<strong>Senza funzione audio <code>.1</code>:</strong> può trovarsi altrove, per esempio <code>00:1f.3</code>. Elenca controller e driver come <code>snd_hda_intel</code>. Per impostazione predefinita <strong>nessuno</strong> è selezionato; scegli solo quelli necessari."
},
"pickVm":{
"title":"Scegli la VM di destinazione",
"body":"Scegli la VM. Richiede q35 e riutilizza le voci GPU esistenti dove possibile. BIOS/UEFI è un’impostazione separata, non un tipo di macchina. Non cambia automaticamente chipset o avvio del guest installato.",
"imageAlt":"Selezione VM per nome, ID e stato"
},
"switchMode":{
"title":"Gestire assegnazioni esistenti",
"intro":"Lo script scansiona ogni configurazione VM e ogni configurazione LXC sull'host alla ricerca del GPU selezionato. Tre possibili risultati:",
"items":[
"<strong>GPU disponibile.</strong> Prosegue senza rimuovere assegnazioni.",
"<strong>Assegnata a un’altra VM.</strong> Arresta prima la sorgente. Puoi <em>mantenere le voci disattivando l’avvio automatico</em> oppure <em>rimuoverle mantenendo l’avvio automatico</em>. Con <code>vfio-pci</code> già attivo e nessuna modifica host necessaria, il trasferimento VM→VM può evitare il riavvio host.",
"<strong>GPU usata da LXC.</strong> Nei container normali scegli <em>mantenere la configurazione GPU e disattivare l’avvio automatico</em> o <em>rimuovere la configurazione del dispositivo GPU mantenendo l’avvio automatico</em>. La rimozione elimina le voci <code>devN</code> e, per AMD/Intel, anche le vecchie regole <code>/dev/dri</code> <code>lxc.mount.entry</code> e <code>lxc.cgroup2.devices.allow</code>. I container OCI conservano la configurazione e vengono fermati con l’avvio automatico disattivato; rimuovi la loro GPU tramite OCI manager Apps. Il rilevamento dei conflitti avviene per famiglia di dispositivi GPU e può includere altre schede della stessa famiglia."
"imageAlt":"Offerta di dialogo per rimuovere il GPU da un LXC prima di assegnarlo al VM",
"smartTitle":"Verificare l’audio associato rimuovendo la GPU",
"smartBody":"Poi può proporre un elenco di <strong>dispositivi audio forse inutilizzati</strong> nella VM sorgente. Deseleziona quelli ancora necessari. Per esempio può mantenere <code>02:00.1</code> e proporre di rimuovere <code>00:1f.3</code>. La scelta determina la rimozione; non garantisce ogni associazione audio/video."
},
"audioPick":{
"title":"Senza audio .1, scegli i controller necessari",
"body":"Succede solo per Intel iGPU e simili configurazioni split-audio. Una lista di controllo mostra ogni controller audio PCI sull'host (escluso qualsiasi già nel gruppo IOMMU di GPU), etichettato con il suo driver corrente. Selezionare quelli che si desidera - o nessuno, se il VM non ha bisogno di audio dall'hardware host.",
"imageAlt":"finestra di dialogo con ogni controller audio PCI host (BDF + driver) quando il GPU non ha un audio di sibling .1",
"warnBody":"Assegnare l’audio può togliere accesso all’host; il controller non può appartenere anche a un’altra VM attiva. Non selezionare audio superfluo e verifica le assegnazioni. Il segnale acustico della console non proviene necessariamente dall’audio PCI."
"body":"Verifica il piano finale dell’host e della VM e annulla se è errato. Mostra il gruppo IOMMU e il numero dei suoi dispositivi; i membri di un altro slot sono elencati nel passaggio precedente. L’annullamento ferma le modifiche principali, ma non annulla una modifica della configurazione di avvio IOMMU confermata separatamente in precedenza.",
"<code>/etc/modprobe.d/vfio.conf</code> — AMD/Intel: <code>options vfio-pci ids=<vendor:device,...> disable_vga=1</code>. NVIDIA: <code>softdep nvidia pre: vfio-pci</code> (<code>_drm</code>/<code>_modeset</code>/<code>_uvm</code>); l’associazione effettiva è per BDF. AMD aggiunge l’ordine di caricamento <code>softdep</code>: <code>vfio-pci</code> → <code>radeon</code>/<code>amdgpu</code>.",
"Scrive <code>/etc/modprobe.d/iommu_unsafe_interrupts.conf</code> e <code>kvm.conf</code> con <code>allow_unsafe_interrupts=1</code> e <code>ignore_msrs=1</code>. Sono impostazioni dello script, non requisiti universali Windows/macOS; gli interrupt non sicuri riducono la protezione del remapping.",
"<code>/etc/modprobe.d/blacklist.conf</code>: NVIDIA — <code>nouveau</code>/<code>lbm-nouveau</code>; AMD — <code>radeon</code> + <code>amdgpu</code>; Intel — <code>i915</code>. Queste regole per produttore possono influire su altre schede con lo stesso driver. Il modulo <code>nvidia</code> è bloccato <strong>solo</strong> tramite <code>/etc/modprobe.d/proxmenux-nvidia-vfio-blacklist.conf</code> quando <em>tutte</em> le NVIDIA host sono riservate a VFIO.",
"<code>/etc/udev/rules.d/10-proxmenux-vfio-bind.rules</code> + <code>/etc/proxmenux/vfio-bind.bdfs</code> — <strong>Solo NVIDIA.</strong> Applica <code>ATTR'{'driver_override'}'=\"vfio-pci\"</code> al PCI ADD dei BDF registrati, incluse le funzioni del gruppo IOMMU interessato. Fuori da quei gruppi può restare <code>nvidia</code>. La politica BDF non divide gruppi IOMMU hardware.",
"<strong>Solo AMD.</strong> Tenta un dump della ROM da <code>/sys/bus/pci/.../rom</code> o ACPI VFCT in <code>/usr/share/kvm/vbios_<vendor>_<device>.bin</code>. Se riesce, la VM usa <code>romfile=</code>. Un dump valido non garantisce la corretta inizializzazione della GPU.",
"<strong>Solo NVIDIA.</strong> Ferma e disattiva <code>nvidia-persistenced</code>, <code>nvidia-powerd</code>, <code>nvidia-fabricmanager</code> solo se tutte le NVIDIA sono riservate a VFIO. In uso misto mantiene servizi e <code>nvidia</code> per le schede native.",
"<code>update-initramfs -u -k all</code> — funziona solo se uno dei suddetti effettivamente cambiato."
]
},
"vmApply":{
"title":"La configurazione della VM viene applicata tramite qm set",
"body":"La configurazione in <code>/etc/pve/qemu-server/<vmid>.conf</code> viene aggiornata tramite <code>qm set</code>, non modificata direttamente con <code>sed</code>.",
"after1":"Aggiunge <code>x-vga=1</code> per AMD e NVIDIA, <strong>non</strong> Intel. È la politica dello script, non prova che ogni iGPU Intel sia priva di firmware o che il flag causi sempre blocchi.",
"after2":"Ulteriori linee <code>hostpciN</code> sono allegate se il gruppo IOMMU di GPU contiene altri dispositivi che è necessario passare insieme."
},
"reboot":{
"title":"Riavvia se richiesto dalle modifiche host",
"body":"Segui il riavvio richiesto se cambiano avvio o driver e verifica l’associazione attiva prima di avviare la VM. La configurazione salvata non prova che sia attiva. VM→VM con VFIO corretto può evitare il riavvio host.",
"imageAlt":"Riepilogo schermo che mostra ciò che è stato cambiato, seguito da un prompt di riavvio"
}
},
"vendors":{
"heading":"Note per produttore",
"nvidiaHeading":"NVIDIA",
"nvidiaBody":"Mantiene un vecchio accorgimento per <em>Code 43</em>: <code>hidden=1</code>, ID <code>NV43FIX</code> in <code>args</code> e <code>kvm=off</code>. Non è un requisito universale delle GeForce attuali: NVIDIA ha abilitato il passthrough Windows da R465. L’errore può avere altre cause; verifica GPU e driver.",
"nvidiaMultiHeading":"Supporto Multi-GPU NVIDIA",
"nvidiaMultiBody":"Uso misto NVIDIA <strong>per BDF</strong>. Registra funzioni <code>vfio-pci</code> per indirizzo, non solo ID <code>vendor:device</code>. Fuori dai gruppi interessati può mantenere <code>nvidia</code>; verifica con <code>nvidia-smi</code>. Non isola due schede dello stesso gruppo.",
"amdHeading":"AMD",
"amdBody":"Alcune GPU AMD non si resettano dopo l’arresto VM. L’assistente verifica capacità dichiarate, non tutti i cicli reali. <vendorResetLink>vendor-reset</vendorResetLink> supporta dispositivi limitati e richiede kernel compatibile e caricamento anticipato; non viene installato. Anche <em>RadeonResetBugFix</em> su Windows dipende dall’hardware, senza garanzia universale.",
"intelHeading":"Intel iGPU",
"intelBody":"Passthrough completo Intel iGPU e SR-IOV sono distinti. L’assistente riserva il dispositivo a una VM senza <code>x-vga=1</code>. <sriovLink>i915-sriov-dkms</sriovLink> richiede hardware/kernel supportati; «UHD 630+» non è una regola di compatibilità. Prevedi accesso alternativo all’host."
},
"verification":{
"heading":"Verifica"
},
"troubleshoot":{
"heading":"Risoluzione dei problemi",
"code43Title":"Codice 43 in Windows (NVIDIA)",
"code43Body":"Code 43 non prova un errore di mascheramento. Controlla <code>qm config VMID | grep -E \"cpu|args\"</code> con VMID reale, poi <code>hidden=1</code> e <code>hv_vendor_id=NV43FIX</code>. Verifica anche driver guest, firmware e assegnazione. Ripetere può terminare se già assegnata.",
"amdResetTitle":"AMD GPU funziona una volta, fallisce sul riavvio di VM",
"amdResetBody":"Un reset fallito è una possibile causa. Riavvio o spegnimento completo possono aiutare temporaneamente. Verifica compatibilità e caricamento anticipato di <code>vendor-reset</code>; <code>softdep amdgpu pre: vendor-reset</code> da solo non garantisce caricamento prima di VFIO. Anche <em>RadeonResetBugFix</em> richiede una GPU compatibile.",
"stuckBootTitle":"Avvio bloccato VM / GPU non rilevato",
"stuckBootBody":"Controlla l’indirizzo reale con <code>lspci -nnk -s PCI_ADDRESS</code>; atteso <code>Kernel driver in use: vfio-pci</code>. Sostituisci PCI_ADDRESS. Se resta il driver nativo, verifica la politica di associazione, non solo <code>/etc/modprobe.d/blacklist.conf</code>; NVIDIA usa stato BDF. Leggi <code>dmesg | grep vfio</code>. Dopo correzioni, <code>update-initramfs -u -k all</code> e riavvio pianificato.",
"darkTitle":"Consolle Host va scuro dopo il riavvio e non posso SSH in",
"darkBody":"Lo schermo nero non prova che l’host sia spento. Se fallisce anche SSH, controlla rete e controller inclusi nel gruppo IOMMU. Recupera accesso via IPMI, seriale o ambiente di ripristino; verifica <code>/etc/pve/qemu-server/<vmid>.conf</code> e annulla solo assegnazioni/regole pertinenti. Non eliminare altra configurazione.",
"logTitle":"Controlla il registro di installazione",
"logBody":"Ogni esecuzione scrive <code>/tmp/add_gpu_vm.log</code>. Allegalo alle richieste di assistenza."
},
"revert":{
"heading":"Annullare le modifiche manualmente",
"intro":"Arresta la VM e rimuovi solo le assegnazioni PCI pertinenti da Hardware o con l’indice esplicito sotto. Non restituisce ancora la GPU al driver host. Usa Cambia modalità GPU per questa transizione e verifica i guest interessati."
},
"related":{
"heading":"Vedi anche",
"items":[
{
"label":"Installare driver NVIDIA (Host)",
"href":"/docs/hardware/nvidia-host",
"tail":" — prepara il driver per schede rimaste sull’host; una GPU in VFIO non può usarlo contemporaneamente."
},
{
"label":"Aggiungi GPU a LXC",
"href":"/docs/hardware/igpu-acceleration-lxc",
"tail":"— modello alternativo: condividere il GPU con più contenitori invece di dedicarlo a un VM."
},
{
"label":"Cambia modalità GPU (VM ↔ LXC)",
"href":"/docs/hardware/switch-gpu-mode",
"tail":" — passa la stessa GPU fra condivisione e assegnazione esclusiva."
},
{
"label":"Comandi di passaggio GPU",
"href":"/docs/help-info/gpu-commands",
"tail":"— lspci, IOMMU verifica, qm set hostpci riferimento."
