# 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

```bash
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

```bash
sudo reboot
```

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

### Step 3: Verify Setup (After Reboot)

```bash
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

```bash
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:

```yaml
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:
```bash
lspci -nnk -s c5:00.0
```

Should show: `Kernel driver in use: vfio-pci`

If not, manually bind:
```bash
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:
```bash
cat /proc/cmdline | grep iommu
```

Should show: `amd_iommu=on iommu=pt`

If not present:
```bash
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:
```bash
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:
```bash
sudo rm /etc/modprobe.d/vfio.conf
```

2. Edit GRUB to remove `vfio-pci.ids=...`:
```bash
sudo nano /etc/default/grub
sudo update-grub
```

3. Update initramfs and reboot:
```bash
sudo update-initramfs -u
sudo reboot
```

## References

- [dockurr/windows](https://github.com/dockur/windows) - Windows container image
- [AMD GPU Passthrough Guide](https://wiki.archlinux.org/title/PCI_passthrough_via_OVMF)
- [VFIO Documentation](https://www.kernel.org/doc/html/latest/driver-api/vfio.html)