scripts/portainer-compose-stacks/windows/GPU-PASSTHROUGH.md

AMD Strix Halo iGPU Passthrough to Windows Container

This guide configures PCI passthrough for the AMD Strix Halo integrated GPU to the Windows Docker container, enabling GPU-accelerated applications.

Problem

The Windows container was showing "Red Hat VirtIO GPU DOD Controller" instead of the AMD GPU because:

• IOMMU was disabled (amd_iommu=off)
• GPU was not passed through at PCI level
• Only /dev/dri devices were exposed (insufficient for Windows)

Solution Overview

1. Enable AMD IOMMU in kernel boot parameters
2. Bind GPU and audio devices to vfio-pci driver
3. Configure QEMU to pass through PCI devices
4. Restart container and install AMD drivers in Windows

Hardware Details

• GPU: AMD Strix Halo iGPU (PCI: c5:00.0, ID: 1002:1586)
• Audio: HDMI Audio Controller (PCI: c5:00.1, ID: 1002:1640)

Setup Instructions

Step 1: Run Setup Script

cd /mnt/shared/DEV/repos/d-popov.com/scripts/portainer-compose-stacks/windows
sudo ./setup-gpu-passthrough.sh

This script will:

• Enable IOMMU in GRUB (amd_iommu=on iommu=pt)
• Configure VFIO to claim the GPU devices
• Update initramfs with VFIO modules
• Create necessary configuration files

Step 2: Reboot

sudo reboot

IMPORTANT: The system MUST be rebooted for IOMMU and VFIO changes to take effect.

Step 3: Verify Setup (After Reboot)

cd /mnt/shared/DEV/repos/d-popov.com/scripts/portainer-compose-stacks/windows
./verify-gpu-passthrough.sh

Expected output:

• ✓ IOMMU is enabled
• ✓ vfio_pci module loaded
• ✓ GPU bound to vfio-pci
• ✓ Audio bound to vfio-pci
• ✓ /dev/vfio/vfio exists

Step 4: Start Windows Container

cd /mnt/shared/DEV/repos/d-popov.com/scripts/portainer-compose-stacks/windows
docker-compose down  # Stop if running
docker-compose up -d

Step 5: Install AMD Drivers in Windows

1. Connect to Windows via RDP: localhost:3389
2. Open Device Manager
3. You should see "AMD Display Adapter" (may show with warning)
4. Download AMD Radeon drivers for Windows 11
5. Install the drivers
6. Reboot Windows
7. Verify GPU in Task Manager → Performance → GPU

Docker Compose Configuration

The configuration includes:

environment:
  GPU: "Y"
  ARGUMENTS: "-device vfio-pci,host=c5:00.0,addr=0x02,multifunction=on -device vfio-pci,host=c5:00.1,addr=0x02.1"
devices:
  - /dev/vfio/vfio

This passes through:

• c5:00.0: AMD GPU
• c5:00.1: HDMI Audio
• addr=0x02: Virtual PCI slot in guest
• multifunction=on: Allows multiple functions on same slot

Troubleshooting

GPU still shows VirtIO after reboot

Check if GPU is bound to vfio-pci:

lspci -nnk -s c5:00.0

Should show: Kernel driver in use: vfio-pci

If not, manually bind:

echo "0000:c5:00.0" | sudo tee /sys/bus/pci/drivers/amdgpu/unbind
echo "1002 1586" | sudo tee /sys/bus/pci/drivers/vfio-pci/new_id

IOMMU not enabled after reboot

Check kernel parameters:

cat /proc/cmdline | grep iommu

Should show: amd_iommu=on iommu=pt

If not present:

sudo nano /etc/default/grub
# Add to GRUB_CMDLINE_LINUX_DEFAULT: amd_iommu=on iommu=pt
sudo update-grub
sudo reboot

Container fails to start

Check logs:

docker logs windows

Common issues:

• VFIO device not found: Run verification script
• Permission denied: Ensure container is privileged: true
• Device busy: Another driver may be using the GPU

GPU not detected in Windows

1. Check Device Manager for unknown devices
2. Try installing AMD Chipset drivers first
3. Use AMD Auto-Detect tool for driver installation
4. Check Windows Event Viewer for driver errors

Performance Notes

• Full GPU acceleration: Direct PCI passthrough provides near-native performance
• VRAM: Windows will see the full iGPU VRAM allocation
• Display output: Use RDP/VNC (no physical display from container)
• 3D acceleration: Fully supported (DirectX, OpenGL, Vulkan)

Limitations

• Host cannot use the iGPU while passed through to the container
• Physical display outputs from the GPU won't work (headless only)
• USB devices may need separate passthrough configuration
• Some GPU features may require CPU pinning for best performance

Files Modified

• /etc/default/grub - IOMMU kernel parameters
• /etc/modprobe.d/vfio.conf - VFIO driver binding
• /etc/initramfs-tools/modules - VFIO modules in initramfs
• docker-compose.yml - PCI passthrough arguments

Reverting Changes

To restore GPU to host:

1. Remove VFIO configuration:

sudo rm /etc/modprobe.d/vfio.conf

2. Edit GRUB to remove vfio-pci.ids=...:

sudo nano /etc/default/grub
sudo update-grub

3. Update initramfs and reboot:

sudo update-initramfs -u
sudo reboot

References

• dockurr/windows - Windows container image
• AMD GPU Passthrough Guide
• VFIO Documentation