too lazy to come up with a helpful commit message :)

memo/kvm-virtio-accel3D.md

@@ -0,0 +1,116 @@
+这是一个关于 **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 协议。
+
+  ```xml
+  <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`)：
+
+    ```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 渲染节点。
+
+```bash
+# 检查组
+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`。
+
+```xml
+<video>
+  <model type="virtio" heads="1" primary="yes">
+    <acceleration accel3d="yes"/>
+  </model>
+    ...
+</video>
+```
+
+2. **图形部分** (`<graphics>`)：移除 `<gl>` 节点，改为使用 `egl-headless`。
+
+```xml
+<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`
+
+     ```conf
+     VIDEO_CARDS="virtgl"
+     ```
+
+   - 或 `/etc/portage/package.use/00video_cards`
+
+     ```conf
+     */* VIDEO_CARDS: virtgl
+     ```
+
+2. **安装必要软件包**：
+
+   ```sh
+   emerge --ask --changed-use media-libs/mesa
+   ```
+
+3. **内核配置**： 需开启 DRM 和 Virtio GPU 支持。
+
+### 4. 重启