dotfiles/memo/kvm-virtio-accel3D.md

这是一个关于 Linux (Arch) 宿主机 + Linux (Gentoo) 客户机 在 KVM/QEMU 环境下启用 Virtio-GPU 3D 加速 遇到黑屏问题的非完整排查与解决记录。

What

• 环境：Host: Arch Linux (Kernel 6.x) | Guest: Gentoo Linux | QEMU v10.x。

• 配置：使用 virtio-vga 或 virtio-gpu 显卡，配合 SPICE 协议。

  <video>
    <model type="virtio" heads="1" primary="yes">
        <acceleration accel3d="yes"/>
    </model>
  </video>
  
  <graphics type="spice">
    <listen type="none"/>
    <image compression="off"/>
    <gl enable="yes" rendernode="/dev/dri/by-path/pci-0000:00:02.0-render"/>
  </graphics>
  

• 现象：

  • 虚拟机启动后黑屏，无法进入图形界面。

  • SSH 连接正常，系统内核正常运行。

  • SPICE 窗口内能看到鼠标光标（表示连接建立），但无画面。

  • 关键日志 (/var/log/libvirt/qemu/xxx.log)：

    warning: console: no gl-unblock within one second
    warning: spice: no gl-draw-done within one second
    

Why

初步分析为 OpenGL 渲染死锁，可能由以下因素叠加导致：

1. 权限不足：QEMU 进程无法访问宿主机的 /dev/dri/* 设备。

2. XML 配置缺失：未显式开启 virtio 设备的 3D 加速位。

3. 渲染管线冲突：SPICE 直接处理 GL 上下文容易发生阻塞，尤其是当 Guest 从 VGA 模式切换到 GL 模式时。

How

1. 确认权限

QEMU 运行用户（通常是 libvirt-qemu）必须有权访问 GPU 渲染节点。

# 检查组
groups libvirt-qemu

# 如果没有 'render' 组，将加之
sudo gpasswd -a libvirt-qemu render

# 重启
sudo systemctl restart libvirtd

2. EGL-Headless 分离渲染

这是解决黑屏死锁最稳妥的方案。通过引入 egl-headless，将 OpenGL 渲染（在后台 GPU 完成）与 SPICE 显示传输（在前台完成）解耦。

1. 显卡部分 (<video>)：必须显式开启 accel3d。

<video>
  <model type="virtio" heads="1" primary="yes">
    <acceleration accel3d="yes"/>
  </model>
    ...
</video>

2. 图形部分 (<graphics>)：移除 <gl> 节点，改为使用 egl-headless。

<graphics type="egl-headless">
  <gl rendernode="/dev/dri/by-path/pci-0000:00:02.0-render"/>
</graphics>

<graphics type="spice">
  <listen type="none"/>
  <image compression="off"/>
</graphics>

3. 客户机配置 （Gentoo）

在 Gentoo Guest 内部，确保驱动栈完整。

1. Portage 配置 ( 或其他位置)：

   • /etc/portage/make.conf

     VIDEO_CARDS="virtgl"
     

   • 或 /etc/portage/package.use/00video_cards

     */* VIDEO_CARDS: virtgl
     

2. 安装必要软件包：

   emerge --ask --changed-use media-libs/mesa
   

3. 内核配置： 需开启 DRM 和 Virtio GPU 支持。

4. 重启