ProxMenux/web/messages/es/docs/hardware/gpu-vm-passthrough.json

{
  "meta": {
    "title": "Añadir GPU a VM | Documentación de ProxMenux",
    "description": "Asigna una GPU física a una VM de Proxmox. ProxMenux revisa IOMMU, configura VFIO y dispositivos de la VM y detecta conflictos con otras VM o LXC."
  },
  "header": {
    "title": "Añadir GPU a VM (Passthrough)",
    "description": "Detecta GPU Intel, AMD o NVIDIA y prepara acceso directo desde una VM. Revisa IOMMU y los dispositivos asociados, configura VFIO y la VM y aplica sus reglas de compatibilidad. Comprueba siempre todos los dispositivos afectados.",
    "section": "Hardware: GPU y Coral-TPU"
  },
  "intro": {
    "title": "Qué hace",
    "body": "Automatiza la configuración del host y <code>hostpci</code> descrita en la <pveLink>documentación de passthrough PCI de Proxmox</pveLink>. Comprueba asignaciones en <em>otros</em> invitados y ofrece resolver conflictos. No garantiza compatibilidad con cualquier GPU, método de reinicio o controlador invitado."
  },
  "who": {
    "heading": "¿Para quién es esto?",
    "body": "Para que una <strong>máquina virtual</strong> use directamente una GPU mediante VFIO. Mientras esté vinculada a VFIO, el controlador del host no puede usarla, aunque la VM esté parada. Para compartirla con <em>LXC</em>, usa <lxcLink>Añadir GPU a LXC</lxcLink>."
  },
  "prereqs": {
    "title": "Antes de empezar",
    "gpu": "<strong>GPU compatible</strong> instalada físicamente. El script detecta Intel, AMD y NVIDIA con <code>lspci</code>.",
    "gpuCheck": "lspci | grep -iE 'VGA|3D|Display'",
    "iommu": "<strong>Soporte IOMMU</strong> en hardware y firmware cuando lo requiera (Intel VT-d o AMD-Vi). Comprueba el sistema y puede añadir parámetros Linux; no cambia BIOS/UEFI ni demuestra que un IOMMU inactivo esté desactivado en firmware.",
    "q35": "Este asistente exige tipo de máquina <strong>q35</strong> y rechaza <code>i440fx</code>. El chipset es independiente de BIOS/UEFI; cambiarlo en una VM existente requiere planificación y no se hace automáticamente.",
    "q35Check": "qm config VMID | grep machine",
    "moreGpus": "Prepara <strong>otra GPU o acceso alternativo</strong> mediante SSH, IPMI o serie. La consola puede perder imagen al reservar la GPU principal. En <em>NVIDIA</em>, otra tarjeta fuera del grupo IOMMU afectado puede seguir en el host.",
    "nvidiaInstalled": "Con <nvidiaLink>NVIDIA instalado en el host</nvidiaLink>, las funciones elegidas se reservan para <code>vfio-pci</code>, no para <code>nvidia</code>. El módulo <code>nvidia</code> puede seguir disponible para <strong>otras</strong> tarjetas fuera del grupo IOMMU afectado. Verifícalas con <code>nvidia-smi</code>."
  },
  "pickOne": {
    "title": "Asignación exclusiva a VM o compartición LXC",
    "body": "Una GPU vinculada a <code>vfio-pci</code> para passthrough a VM no puede usarla simultáneamente el host ni un LXC. Si tienes dos GPUs, puedes dedicar una a cada ruta. Si solo tienes una, elige:",
    "vmItem": "<strong>VM:</strong> acceso directo y exclusivo para esa VM.",
    "lxcItem": "<strong>LXC (<lxcLink>Añadir GPU a LXC</lxcLink>):</strong> comparte el dispositivo con host y otros contenedores mediante el controlador nativo."
  },
  "running": {
    "heading": "Ejecutar el instalador",
    "body": "Abre ProxMenux y ve a <strong>Hardware: GPU y Coral-TPU → Añadir GPU a VM</strong>.",
    "imageAlt": "Opción del menú para añadir GPU a VM"
  },
  "howRuns": {
    "heading": "Cómo funciona el script",
    "body": "Detecta y selecciona antes de aplicar los cambios principales y confirma el plan en un resumen final. Activar IOMMU tiene una confirmación anterior y puede modificar ya el arranque. La limpieza posterior de audio asociado también puede pedir una elección."
  },
  "walkthrough": {
    "heading": "Proceso paso a paso",
    "detect": {
      "title": "Detectar GPUs y comprobar IOMMU",
      "body": "Considera IOMMU activo solo si el kernel en ejecución tiene <code>intel_iommu=on</code> o <code>amd_iommu=on</code> y existen grupos IOMMU. Si el parámetro ya está guardado para el próximo arranque, continúa en modo pendiente de reinicio; si no, con confirmación aparte puede añadirlo con <code>iommu=pt</code>. Elige <code>/etc/kernel/cmdline</code> si encuentra una marca ZFS como <code>root=ZFS=</code>; si no, <code>/etc/default/grub</code>. Es una heurística, no una prueba del cargador. Reinicia para activar el cambio y revisa los grupos reales.",
      "tipTitle": "¿Ya configuraste la postinstalación?",
      "tipBody": "Si el <postLink>soporte VFIO IOMMU</postLink> ya está configurado y activo en el kernel, supera la comprobación. Guardarlo para el próximo arranque no prueba que esté activo ahora.",
      "imageAlt": "Lista de GPUs detectadas con fabricante y dirección PCI"
    },
    "preflight": {
      "title": "Elegir GPU y ejecutar comprobaciones previas",
      "intro": "Una vez eliges la GPU, el script ejecuta una serie de comprobaciones que pueden bloquear el progreso:",
      "items": [
        "<strong>Protección SR-IOV.</strong> Rechaza VF y PF con VF activas porque configura dispositivos completos, no SR-IOV. Configura SR-IOV por separado con hardware compatible.",
        "<strong>Una sola GPU.</strong> La consola local puede perder su salida al reservarla para VFIO. Comprueba antes el acceso SSH o web desde otro equipo.",
        "<strong>Política de reinicio AMD.</strong> Lee <code>/sys/bus/pci/devices/&lt;pci&gt;/reset_method</code>. Una APU o dedicada sin FLR queda <em>bloqueada por la política del asistente</em>; un subtipo desconocido sin FLR exige confirmación. No demuestra que sea imposible en todo entorno.",
        "<strong>Estado D3cold.</strong> El asistente bloquea tarjetas AMD que indican <code>D3cold</code> por riesgo de fallo al activarlas. Revisa alimentación y firmware antes de continuar.",
        "<strong>Grupo IOMMU.</strong> Lee <code>/sys/kernel/iommu_groups/</code> e incluye <em>todos los miembros que no sean puentes</em>, incluso controladores de red o discos. Si el grupo contiene dispositivos de otro slot, el script los muestra antes del resumen; comprueba que el host no necesite ninguno. Si falta reiniciar para activar IOMMU, solo puede planificar inicialmente la función GPU; comprueba el aislamiento después."
      ],
      "audioIntro": "<strong>Audio asociado.</strong> Dos casos según dónde esté el controlador:",
      "audioDgpu": "<strong>GPU dedicada:</strong> el audio HDMI suele ocupar la función <code>.1</code> del mismo slot y se incluye al detectarlo. Si el host lo usaba, pierde acceso al reservarlo para la VM.",
      "audioIgpu": "<strong>Sin función de audio <code>.1</code>:</strong> puede estar en otro dispositivo, como <code>00:1f.3</code>. Lista controladores y sus drivers, por ejemplo <code>snd_hda_intel</code>. Por defecto no selecciona <strong>ninguno</strong>; elige solo los necesarios."
    },
    "pickVm": {
      "title": "Elige la VM destino",
      "body": "Elige la VM de la lista. Exige q35 y reutiliza entradas GPU existentes cuando puede. BIOS/UEFI es una opción distinta, no un tipo de máquina. No cambia automáticamente el chipset ni el arranque del invitado instalado.",
      "imageAlt": "Selección de VM por nombre, ID y estado"
    },
    "switchMode": {
      "title": "Resolver asignaciones existentes",
      "intro": "El script escanea cada config de VM y cada config de LXC en el host buscando la GPU que elegiste. Tres resultados posibles:",
      "items": [
        "<strong>GPU disponible.</strong> Continúa sin retirar asignaciones.",
        "<strong>Asignada a otra VM.</strong> Detén primero la VM origen. Puedes <em>conservar sus entradas y desactivar el arranque automático</em> o <em>retirarlas conservando el arranque automático</em>. Si ya usa <code>vfio-pci</code> y no requiere cambios del host, el traspaso VM→VM puede evitar reiniciar el host.",
        "<strong>Usada por LXC.</strong> En contenedores normales elige <em>conservar configuración y desactivar arranque automático</em> o <em>eliminar la configuración de la GPU y conservar arranque automático</em>. Esta opción elimina las entradas <code>devN</code> y, en AMD/Intel, también las reglas antiguas <code>lxc.mount.entry</code> de <code>/dev/dri</code> y <code>lxc.cgroup2.devices.allow</code>. OCI conserva la configuración y se detiene sin arranque automático; elimina su GPU desde Apps del gestor OCI. La detección por familia puede afectar a otras tarjetas similares."
      ],
      "imageAlt": "Diálogo que ofrece eliminar la GPU de un LXC antes de asignarla a la VM",
      "smartTitle": "Revisión de audio asociado al retirar la GPU",
      "smartBody": "Después ofrece una lista de <strong>audio posiblemente sin uso</strong> en la VM origen. Desmarca lo que aún necesite. Por ejemplo, puede conservar <code>02:00.1</code> y ofrecer retirar <code>00:1f.3</code>. La lista decide qué audio adicional se elimina; no garantiza toda asociación entre pantalla y audio."
    },
    "audioPick": {
      "title": "Si no hay audio .1, selecciona los controladores que necesites",
      "body": "Solo ocurre para iGPUs Intel y setups similares con audio separado. Una checklist muestra cada controlador de audio PCI del host (excluyendo cualquiera ya en el grupo IOMMU de la GPU), etiquetado con su driver actual. Selecciona los que quieras — o ninguno, si la VM no necesita audio del hardware del host.",
      "imageAlt": "Diálogo checklist con cada controlador de audio PCI del host (BDF + driver) cuando la GPU no tiene audio hermano .1",
      "warnTitle": "No selecciones audio que necesita el host",
      "warnBody": "Asignar audio puede dejar al host sin acceso; tampoco puede pertenecer a otra VM activa a la vez. Deja audio opcional sin seleccionar si no lo necesitas y revisa sus asignaciones. El pitido de consola no procede necesariamente del audio PCI."
    },
    "summary": {
      "title": "Revisar el resumen de confirmación",
      "body": "Revisa el plan final y cancela si no es correcto. Muestra el grupo IOMMU y su número de dispositivos; los miembros de otro slot aparecen en el paso anterior. Cancelar detiene los cambios principales, pero no revierte una activación de IOMMU confirmada anteriormente.",
      "imageAlt": "Resumen de cambios previstos en host y VM"
    },
    "hostApply": {
      "title": "Se aplican los cambios del host",
      "intro": "La fase de aplicación cambia host y VM. La limpieza de audio asociado aún puede pedir una elección. Puede modificar:",
      "items": [
        "<code>/etc/modules</code> — añade <code>vfio</code>, <code>vfio_iommu_type1</code>, <code>vfio_pci</code> (más <code>vfio_virqfd</code> en kernels &lt; 6.2).",
        "<code>/etc/modprobe.d/vfio.conf</code> — AMD/Intel: <code>options vfio-pci ids=&lt;vendor:device,...&gt; disable_vga=1</code>. NVIDIA: <code>softdep nvidia pre: vfio-pci</code> (<code>_drm</code>/<code>_modeset</code>/<code>_uvm</code>); la asignación real es por BDF. AMD añade orden de carga <code>softdep</code>: <code>vfio-pci</code> → <code>radeon</code>/<code>amdgpu</code>.",
        "Escribe <code>/etc/modprobe.d/iommu_unsafe_interrupts.conf</code> y <code>kvm.conf</code> con <code>allow_unsafe_interrupts=1</code> e <code>ignore_msrs=1</code>. Son ajustes del script, no requisitos universales de Windows/macOS; permitir interrupciones inseguras reduce esa protección.",
        "<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>. Estas reglas por fabricante pueden afectar a otras tarjetas con el mismo controlador. El módulo <code>nvidia</code> se bloquea <strong>solo</strong> mediante <code>/etc/modprobe.d/proxmenux-nvidia-vfio-blacklist.conf</code> cuando <em>todas</em> las NVIDIA del host están reservadas a VFIO.",
        "<code>/etc/udev/rules.d/10-proxmenux-vfio-bind.rules</code> + <code>/etc/proxmenux/vfio-bind.bdfs</code> — <strong>Solo NVIDIA.</strong> Aplica <code>ATTR'{'driver_override'}'=\"vfio-pci\"</code> al evento PCI ADD de BDF registrados, incluidas funciones del grupo IOMMU afectado. Fuera de esos grupos puede conservarse <code>nvidia</code>. La política por BDF no divide grupos IOMMU.",
        "<strong>Solo AMD.</strong> Intenta extraer ROM de <code>/sys/bus/pci/.../rom</code> o ACPI VFCT a <code>/usr/share/kvm/vbios_&lt;vendor&gt;_&lt;device&gt;.bin</code>. Si funciona, usa <code>romfile=</code>. Una ROM válida no garantiza que la GPU se inicialice.",
        "<strong>Solo NVIDIA.</strong> Detiene y deshabilita <code>nvidia-persistenced</code>, <code>nvidia-powerd</code>, <code>nvidia-fabricmanager</code> solo cuando todas las NVIDIA están reservadas para VFIO. En uso mixto conserva los servicios y <code>nvidia</code> para las tarjetas nativas.",
        "<code>update-initramfs -u -k all</code> — solo se ejecuta si algo de lo de arriba ha cambiado realmente."
      ]
    },
    "vmApply": {
      "title": "La config de la VM se aplica vía qm set",
      "body": "La config de la VM en <code>/etc/pve/qemu-server/&lt;vmid&gt;.conf</code> se actualiza vía <code>qm set</code> (nunca por <code>sed</code> directo):",
      "after1": "Añade <code>x-vga=1</code> para AMD y NVIDIA, <strong>no</strong> para Intel. Es la política del script; no demuestra que todas las iGPU Intel carezcan de firmware o que ese ajuste siempre provoque bloqueos.",
      "after2": "Se añaden líneas <code>hostpciN</code> adicionales si el grupo IOMMU de la GPU contiene otros dispositivos que necesitas pasar juntos."
    },
    "reboot": {
      "title": "Reinicia si lo requiere el cambio del host",
      "body": "Sigue el aviso de reinicio si cambia arranque o controladores y comprueba la vinculación activa antes de iniciar la VM. Guardar configuración no prueba que esté aplicada. Un traspaso VM→VM con VFIO correcto puede evitar reiniciar el host.",
      "imageAlt": "Pantalla de resumen mostrando qué se cambió, seguida de un prompt de reinicio"
    }
  },
  "vendors": {
    "heading": "Notas por fabricante",
    "nvidiaHeading": "NVIDIA",
    "nvidiaBody": "Conserva un ajuste heredado para <em>Code 43</em>: <code>hidden=1</code>, ID <code>NV43FIX</code> en <code>args</code> y <code>kvm=off</code>. No es requisito universal de GeForce actuales: NVIDIA añadió soporte de passthrough Windows en R465. El error puede tener otras causas; verifica GPU y controlador.",
    "nvidiaMultiHeading": "Soporte NVIDIA multi-GPU",
    "nvidiaMultiBody": "Admite uso mixto NVIDIA <strong>por BDF</strong>. Registra funciones de <code>vfio-pci</code> por dirección, no solo por ID <code>vendor:device</code>. Fuera de los grupos afectados pueden conservar <code>nvidia</code>; compruébalas con <code>nvidia-smi</code>. No aísla dos tarjetas del mismo grupo.",
    "amdHeading": "AMD",
    "amdBody": "Algunas AMD fallan al reiniciar tras parar una VM. El asistente comprueba capacidades declaradas, no todos los ciclos reales. <vendorResetLink>vendor-reset</vendorResetLink> admite una lista limitada y exige kernel compatible y carga temprana; no lo instala. <em>RadeonResetBugFix</em> en Windows también depende del hardware, sin garantía universal.",
    "intelHeading": "iGPU Intel",
    "intelBody": "Asignar toda la iGPU Intel y usar SR-IOV son procesos distintos. Este asistente reserva el dispositivo para una VM y omite <code>x-vga=1</code>. <sriovLink>i915-sriov-dkms</sriovLink> requiere hardware y kernel compatibles; «UHD 630+» no es una regla válida. Prevé acceso alternativo al host."
  },
  "verification": {
    "heading": "Verificación"
  },
  "troubleshoot": {
    "heading": "Solución de problemas",
    "code43Title": "Code 43 en Windows (NVIDIA)",
    "code43Body": "Code 43 no prueba un fallo de ocultación. Consulta <code>qm config VMID | grep -E \"cpu|args\"</code> sustituyendo VMID y revisa <code>hidden=1</code> y <code>hv_vendor_id=NV43FIX</code>. Comprueba también controlador invitado, firmware y asignación. Repetir el script puede salir si ya está asignada.",
    "amdResetTitle": "La GPU AMD funciona una vez, falla al reiniciar la VM",
    "amdResetBody": "Una causa posible es el fallo de reinicio de la GPU. Reiniciar o apagar el host puede recuperarla temporalmente. Comprueba soporte de <code>vendor-reset</code> y carga temprana; <code>softdep amdgpu pre: vendor-reset</code> no garantiza por sí solo cargar antes de VFIO. <em>RadeonResetBugFix</em> en Windows también requiere GPU compatible.",
    "stuckBootTitle": "VM colgada arrancando / GPU no detectada",
    "stuckBootBody": "Consulta la dirección real con <code>lspci -nnk -s PCI_ADDRESS</code>; espera <code>Kernel driver in use: vfio-pci</code>. Sustituye PCI_ADDRESS. Si sigue el driver nativo, revisa su política de vinculación, no solo <code>/etc/modprobe.d/blacklist.conf</code>; NVIDIA usa estado por BDF. Consulta <code>dmesg | grep vfio</code>. Tras corregir configuración, ejecuta <code>update-initramfs -u -k all</code> y sigue el plan de reinicio.",
    "darkTitle": "La consola del host se queda a oscuras tras reiniciar y no puedo entrar por SSH",
    "darkBody": "Una pantalla negra no prueba que el host esté caído. Si falla SSH, revisa red y controladores incluidos en el grupo IOMMU. Recupera acceso por IPMI, serie o entorno de rescate; revisa <code>/etc/pve/qemu-server/&lt;vmid&gt;.conf</code> y revierte solo asignaciones y reglas relacionadas. No borres configuración ajena.",
    "logTitle": "Revisa el log de instalación",
    "logBody": "Cada ejecución escribe <code>/tmp/add_gpu_vm.log</code>. Adjunta el registro al pedir ayuda."
  },
  "revert": {
    "heading": "Deshacer cambios manualmente",
    "intro": "Detén la VM y retira solo sus asignaciones PCI correspondientes desde Hardware o mediante el índice explícito del ejemplo. Eliminarla de la VM no devuelve la GPU al controlador del host. Para eso usa Cambiar modo de GPU y revisa los invitados afectados antes de confirmar."
  },
  "related": {
    "heading": "Relacionado",
    "items": [
      {
        "label": "Instalar drivers NVIDIA (Host)",
        "href": "/docs/hardware/nvidia-host",
        "tail": " — prepara el controlador para tarjetas que sigan en el host; una GPU en VFIO no puede usarlo a la vez."
      },
      {
        "label": "Añadir GPU a LXC",
        "href": "/docs/hardware/igpu-acceleration-lxc",
        "tail": " — modelo alternativo: comparte la GPU con varios contenedores en lugar de dedicarla a una VM."
      },
      {
        "label": "Cambiar modo de GPU (VM ↔ LXC)",
        "href": "/docs/hardware/switch-gpu-mode",
        "tail": " — cambia la misma GPU entre uso compartido y asignación exclusiva."
      },
      {
        "label": "Comandos de GPU Passthrough",
        "href": "/docs/help-info/gpu-commands",
        "tail": " — referencia de lspci, verificación de IOMMU, qm set hostpci."
      }
    ]
  }
}