{ "meta": { "title": "Adicionar GPU a VM | Documentação ProxMenux", "description": "Atribua uma GPU física a uma VM Proxmox. O ProxMenux verifica IOMMU, configura VFIO e dispositivos VM e deteta conflitos com outras VM ou LXC." }, "header": { "title": "Adicionar GPU a VM (passthrough)", "description": "Deteta GPU Intel, AMD ou NVIDIA para acesso direto numa VM. Verifica IOMMU e dispositivos associados, configura VFIO e VM e aplica regras de compatibilidade. Verifique todos os dispositivos afetados.", "section": "Hardware: GPUs e Coral-TPU" }, "intro": { "title": "O que faz", "body": "Automatiza os passos do anfitrião e hostpci da documentação PCI passthrough Proxmox. Verifica atribuições a outros convidados e propõe soluções para conflitos. Não garante suporte para qualquer GPU, método de reset ou controlador convidado." }, "who": { "heading": "Para quem é isto?", "body": "Para uma máquina virtual usar diretamente a GPU via VFIO. Enquanto estiver associada a VFIO, o controlador do anfitrião não a pode usar, mesmo com a VM parada. Para partilha com LXC, use Adicionar GPU ao LXC." }, "prereqs": { "title": "Antes de começar", "gpu": "GPU compatível fisicamente instalada. O script deteta Intel, AMD e NVIDIA com lspci.", "gpuCheck": "lspci | grep -iE 'VGA|3D|Display'", "iommu": "Suporte IOMMU no hardware e ativação no firmware quando necessária (Intel VT-d ou AMD-Vi). Verifica o sistema e pode configurar Linux; não muda BIOS/UEFI nem prova que IOMMU inativo esteja desativado no firmware.", "q35": "O assistente exige q35 e recusa i440fx. O tipo de máquina é distinto do firmware BIOS/UEFI. Mudar o chipset de uma VM existente exige planeamento e não é automático.", "q35Check": "qm config VMID | grep machine", "moreGpus": "Prepare outra GPU ou acesso alternativo por SSH, IPMI ou série. Reservar a GPU principal pode retirar a imagem local. Em NVIDIA, uma placa fora do grupo IOMMU afetado pode ficar no anfitrião.", "nvidiaInstalled": "Após instalar NVIDIA no anfitrião, as funções escolhidas ficam reservadas a vfio-pci em vez de nvidia. O módulo nvidia pode continuar disponível para outras placas fora do grupo IOMMU afetado. Verifique com nvidia-smi." }, "pickOne": { "title": "Atribuição exclusiva VM ou partilha LXC", "body": "Um GPU ligado a vfio-pci para a passagem de VM não pode ser usado simultaneamente pelo hospedeiro ou por um LXC. Se você tiver duas GPUs, você pode dedicar uma a cada caminho. Se você tem apenas um, escolha:", "vmItem": "VM: acesso direto e exclusivo para essa VM.", "lxcItem": "LXC (Adicionar GPU ao LXC): partilha o dispositivo com anfitrião e outros contentores pelo controlador nativo." }, "running": { "heading": "Executar o instalador", "body": "Abra o ProxMenux e escolha Hardware: GPU e Coral-TPU → Adicionar GPU a VM.", "imageAlt": "Opção do menu para adicionar GPU a VM" }, "howRuns": { "heading": "Como funciona o script", "body": "Deteção e seleção precedem as alterações principais, confirmadas num resumo final. Ativar IOMMU tem confirmação anterior e pode já alterar o arranque. A limpeza posterior de áudio pode também pedir uma escolha." }, "walkthrough": { "heading": "Procedimento passo a passo", "detect": { "title": "Detectar GPUs e verificar IOMMU", "body": "Considera o IOMMU ativo apenas quando o kernel em execução tem intel_iommu=on ou amd_iommu=on e existem grupos IOMMU. Se o parâmetro já estiver guardado para o próximo arranque, continua em modo de reinício pendente; caso contrário, um passo confirmado separadamente pode adicioná-lo com iommu=pt. A sua heurística de ficheiro de arranque utiliza /etc/kernel/cmdline quando aí existe uma marca de raiz ZFS como root=ZFS=; caso contrário, utiliza /etc/default/grub. Essa heurística não é prova do carregador de arranque real. O IOMMU recém-configurado entra em vigor após o reinício; verifique depois os grupos reais.", "tipTitle": "Já configurou a pós-instalação?", "tipBody": "Se o suporte VFIO IOMMU já estiver configurado e ativo no kernel, passa a verificação. Uma definição para o próximo arranque não prova que esteja ativo agora.", "imageAlt": "Lista de GPUs detectadas com fornecedor e endereço PCI" }, "preflight": { "title": "Escolher GPU e executar verificações prévias", "intro": "Uma vez que você escolher o GPU, o script executa uma série de verificações que podem cada bloco mais progresso:", "items": [ "Proteção SR-IOV. Recusa VF e PF com VF ativas porque configura dispositivos completos, não SR-IOV. Configure SR-IOV separadamente em hardware compatível.", "Uma só GPU. A consola local pode perder a imagem ao reservá-la para VFIO. Verifique antes o acesso SSH ou web de outro computador.", "Política de reset AMD. Lê /sys/bus/pci/devices/<pci>/reset_method. APU ou dedicada sem FLR fica bloqueada pela política do assistente; subtipo desconhecido sem FLR exige confirmação. Não prova impossibilidade universal.", "Estado D3cold. Bloqueia placas AMD que indicam D3cold pelo risco de falha na ativação. Verifique alimentação e firmware.", "Análise do grupo IOMMU. Lê /sys/kernel/iommu_groups/ e inclui no plano da VM todos os membros exceto pontes, possivelmente controladores de rede ou de armazenamento. Se o grupo contiver dispositivos de outro slot, o script lista-os antes do resumo; verifique se o anfitrião não precisa de nenhum. Se o IOMMU aguardar reinício, os grupos reais não estão disponíveis e o plano contém inicialmente só a função GPU selecionada; verifique o isolamento após o reinício." ], "audioIntro": "Áudio associado. Dois casos consoante a localização do controlador:", "audioDgpu": "GPU dedicada: o áudio HDMI ocupa frequentemente a função .1 da mesma ranhura PCI e é incluído se detetado. Se o anfitrião o usava, perde acesso ao reservá-lo à VM.", "audioIgpu": "Sem função áudio .1: pode estar noutro dispositivo como 00:1f.3. Lista controladores e drivers como snd_hda_intel. Por predefinição nenhum é selecionado; escolha apenas os necessários." }, "pickVm": { "title": "Escolha a VM de destino", "body": "Escolha a VM. Exige q35 e reutiliza entradas GPU existentes quando possível. BIOS/UEFI é uma definição separada, não um tipo de máquina. Não muda automaticamente o chipset nem o arranque do convidado instalado.", "imageAlt": "Seleção de VM por nome, ID e estado" }, "switchMode": { "title": "Tratar atribuições existentes", "intro": "O script verifica cada configuração do VM e cada configuração do LXC na máquina à procura do GPU que escolheu. Três resultados possíveis:", "items": [ "GPU disponível. Continua sem remover atribuições.", "Atribuída a outra VM. Pare primeiro a origem. Pode manter as entradas e desativar o arranque automático ou removê-las mantendo o arranque automático. Com vfio-pci já ativo e sem alterações necessárias no anfitrião, VM→VM pode evitar reiniciá-lo.", "GPU usada por LXC. Nos contentores normais escolha manter a configuração da GPU e desativar o arranque automático ou remover a configuração do dispositivo GPU, mantendo o arranque automático. A remoção elimina as entradas devN e, em AMD/Intel, também as regras antigas /dev/dri lxc.mount.entry e lxc.cgroup2.devices.allow. Os contentores OCI conservam a configuração e são parados com o arranque automático desativado; remova a sua GPU através de OCI manager Apps. A deteção de conflitos é feita por família de dispositivos GPU e pode abranger outras placas dessa família." ], "imageAlt": "Oferecendo diálogo para remover o GPU de um LXC antes de atribuí-lo ao VM", "smartTitle": "Rever áudio associado ao remover a GPU", "smartBody": "Depois pode propor uma lista de áudio possivelmente sem uso na VM origem. Desmarque o que ainda precisar. Por exemplo, pode manter 02:00.1 e propor remover 00:1f.3. A lista determina as remoções adicionais, sem garantir todas as associações áudio/imagem." }, "audioPick": { "title": "Sem áudio .1, selecione os controladores necessários", "body": "Apenas acontece para configurações de áudio dividido Intel iGPU e semelhantes. Uma lista de verificação mostra cada controlador de áudio PCI no host (excluindo qualquer já no grupo IOMMU do GPU), etiquetado com seu driver atual. Selecione os que você deseja — ou nenhum, se o VM não precisar de áudio do hardware do host.", "imageAlt": "Diálogo de lista de verificação com cada controlador de áudio PCI da máquina (controlador BDF +) quando o GPU não tem áudio .1", "warnTitle": "Não selecione áudio necessário ao anfitrião", "warnBody": "Atribuir áudio pode retirar acesso ao anfitrião; o controlador não pode pertencer também a outra VM ativa. Não selecione áudio desnecessário e verifique as atribuições. O sinal da consola não vem necessariamente do áudio PCI." }, "summary": { "title": "Rever o resumo da confirmação", "body": "Verifique o plano final do anfitrião e da VM e cancele se estiver incorreto. Mostra o grupo IOMMU e o número dos seus dispositivos; os membros de outro slot são listados no passo anterior. O cancelamento impede as alterações principais, mas não reverte uma alteração da configuração de arranque IOMMU confirmada separadamente antes.", "imageAlt": "Resumo das alterações previstas no anfitrião e VM" }, "hostApply": { "title": "As alterações da máquina são aplicadas", "intro": "A fase de aplicação altera anfitrião e VM. A limpeza áudio pode ainda pedir uma escolha. Pode modificar:", "items": [ "/etc/modules — acrescenta vfio, vfio_iommu_type1, vfio_pci (mais vfio_virqfd em kernels < 6.2).", "/etc/modprobe.d/vfio.conf — AMD/Intel: options vfio-pci ids=<vendor:device,...> disable_vga=1. NVIDIA: softdep nvidia pre: vfio-pci (_drm/_modeset/_uvm); a associação efetiva é por BDF. AMD adiciona a ordem de carregamento softdep: vfio-pci → radeon/amdgpu.", "Escreve /etc/modprobe.d/iommu_unsafe_interrupts.conf e kvm.conf com allow_unsafe_interrupts=1 e ignore_msrs=1. São definições do script, não requisitos universais Windows/macOS; interrupções inseguras reduzem a proteção do remapeamento.", "/etc/modprobe.d/blacklist.conf: NVIDIA — nouveau/lbm-nouveau; AMD — radeon + amdgpu; Intel — i915. Estas regras por fabricante podem afetar outras placas com o mesmo controlador. O módulo nvidia é bloqueado apenas por /etc/modprobe.d/proxmenux-nvidia-vfio-blacklist.conf quando todas as NVIDIA do anfitrião estão reservadas a VFIO.", "/etc/udev/rules.d/10-proxmenux-vfio-bind.rules + /etc/proxmenux/vfio-bind.bdfs — Apenas NVIDIA. Aplica ATTR'{'driver_override'}'=\"vfio-pci\" no PCI ADD dos BDF registados, incluindo funções do grupo IOMMU afetado. Fora desses grupos pode manter-se nvidia. A política BDF não divide grupos IOMMU físicos.", "Apenas AMD. Tenta extrair a ROM de /sys/bus/pci/.../rom ou ACPI VFCT para /usr/share/kvm/vbios_<vendor>_<device>.bin. Se conseguir, a VM usa romfile=. Uma extração válida não garante a inicialização bem-sucedida da GPU.", "Apenas NVIDIA. Para e desativa nvidia-persistenced, nvidia-powerd, nvidia-fabricmanager só quando todas as NVIDIA estão reservadas a VFIO. Em uso misto conserva os serviços e nvidia para as placas nativas.", "update-initramfs -u -k all — só é executado se alguma das acima referidas tiver realmente mudado." ] }, "vmApply": { "title": "A configuração do VM é aplicada através de qm set", "body": "A configuração VM em /etc/pve/qemu-server/<vmid>.conf é atualizada via qm set (nunca por sed):", "after1": "Adiciona x-vga=1 para AMD e NVIDIA, não Intel. É a política do script, não prova de que todas as iGPU Intel não têm firmware ou que a opção causa sempre bloqueios.", "after2": "Linhas adicionais de hostpciN são adicionadas se o grupo IOMMU do GPU contém outros dispositivos que você precisa passar juntos." }, "reboot": { "title": "Reinicie se a alteração do anfitrião exigir", "body": "Siga o reinício pedido se mudar arranque ou controladores e verifique a associação ativa antes de iniciar a VM. Configuração guardada não prova ativação. VM→VM com VFIO correto pode evitar reiniciar o anfitrião.", "imageAlt": "Tela de resumo mostrando o que foi alterado, seguido de um prompt de reinicialização" } }, "vendors": { "heading": "Notas por fabricante", "nvidiaHeading": "NVIDIA", "nvidiaBody": "Mantém uma solução antiga para Code 43: hidden=1, ID NV43FIX em args e kvm=off. Não é requisito universal das GeForce atuais: NVIDIA ativou passthrough Windows em R465. O erro pode ter outras causas; verifique GPU e controlador.", "nvidiaMultiHeading": "Suporte para multi-GPU NVIDIA", "nvidiaMultiBody": "Uso misto NVIDIA por BDF. Regista funções vfio-pci por endereço, não só ID vendor:device. Fora dos grupos afetados pode conservar nvidia; verifique com nvidia-smi. Não isola duas placas do mesmo grupo.", "amdHeading": "AMD", "amdBody": "Algumas AMD falham ao repor após parar uma VM. O assistente verifica capacidades declaradas, não todos os ciclos reais. vendor-reset suporta uma lista limitada e exige kernel compatível e carregamento antecipado; não é instalado. RadeonResetBugFix no Windows também depende do hardware, sem garantia universal.", "intelHeading": "Intel iGPU", "intelBody": "Atribuição completa Intel iGPU e SR-IOV são distintos. O assistente reserva o dispositivo a uma VM sem x-vga=1. i915-sriov-dkms exige hardware/kernel suportados; «UHD 630+» não é regra de compatibilidade. Planeie acesso alternativo ao anfitrião." }, "verification": { "heading": "Verificação" }, "troubleshoot": { "heading": "Resolução de problemas", "code43Title": "Código 43 no Windows (NVIDIA)", "code43Body": "Code 43 não prova falha de ocultação. Consulte qm config VMID | grep -E \"cpu|args\" com VMID real, depois hidden=1 e hv_vendor_id=NV43FIX. Verifique também controlador convidado, firmware e atribuição. Repetir pode terminar se já atribuída.", "amdResetTitle": "O AMD GPU funciona uma vez, falha na reinicialização do VM", "amdResetBody": "Falha de reset é uma causa possível. Reiniciar ou desligar e ligar pode ajudar temporariamente. Verifique compatibilidade e carregamento antecipado de vendor-reset; softdep amdgpu pre: vendor-reset só por si não garante carregar antes de VFIO. RadeonResetBugFix também exige GPU compatível.", "stuckBootTitle": "O arranque emperrado do VM / GPU não foi detectado", "stuckBootBody": "Consulte o endereço real com lspci -nnk -s PCI_ADDRESS; esperado Kernel driver in use: vfio-pci. Substitua PCI_ADDRESS. Se permanecer o controlador nativo, verifique a política de associação, não só /etc/modprobe.d/blacklist.conf; NVIDIA usa estado BDF. Leia dmesg | grep vfio. Após corrigir, execute update-initramfs -u -k all e siga o reinício previsto.", "darkTitle": "O console da máquina fica escuro depois de reiniciar e eu não posso SSH em", "darkBody": "Um ecrã preto não prova que o anfitrião esteja parado. Se SSH também falhar, verifique rede e controladores incluídos no grupo IOMMU. Recupere por IPMI, série ou ambiente de recuperação; reveja /etc/pve/qemu-server/<vmid>.conf e reverta só atribuições/regras relacionadas. Não elimine outras configurações.", "logTitle": "Verificar o registo de instalação", "logBody": "Cada execução escreve /tmp/add_gpu_vm.log. Anexe o registo ao pedir ajuda." }, "revert": { "heading": "Reverter alterações manualmente", "intro": "Pare a VM e remova só as atribuições PCI relevantes em Hardware ou com o índice explícito abaixo. Isso não devolve a GPU ao controlador nativo. Use Alterar modo da GPU para essa transição e verifique os convidados afetados." }, "related": { "heading": "Relacionados", "items": [ { "label": "Instalar Drivers NVIDIA (Host)", "href": "/docs/hardware/nvidia-host", "tail": " — prepara o controlador para placas mantidas no anfitrião; uma GPU em VFIO não o pode usar ao mesmo tempo." }, { "label": "Adicionar GPU ao LXC", "href": "/docs/hardware/igpu-acceleration-lxc", "tail": " — modelo alternativo: partilhar o GPU com vários contentores em vez de o dedicar a um VM." }, { "label": "Alterar modo da GPU (VM ↔ LXC)", "href": "/docs/hardware/switch-gpu-mode", "tail": " — alterna a mesma GPU entre partilha e atribuição exclusiva." }, { "label": "Comandos de passagem GPU", "href": "/docs/help-info/gpu-commands", "tail": " — lspci, verificação IOMMU, referência qm set hostpci." } ] } }