1. Virgl 纹理格式能力：一个容易被忽略的关键环节
Virgl 是虚拟化图形栈里非常核心的一层。简单说，它就是让客户机里的 OpenGL 请求能穿透虚拟化边界，最终落到宿主机 GPU 上执行的那座桥。只要你在做 GPU 虚拟化、桌面云、终端虚拟化相关的工作，或者调过虚拟机里 3D 加速异常的问题，八成都会跟 Virgl 打交道。
这几年服务器虚拟化、麒麟天逸终端虚拟化平台这类产品越铺越广，虚拟机里跑 3D 应用、跑 OpenGL 渲染越来越常见，Virgl 的使用频率也跟着水涨船高。但很多人对 Virgl 的理解停留在“它是一个软件渲染/转发层”，一旦深入进去，就会碰到一个非常底层、又非常绕的问题：纹理格式能力是怎么从宿主机传递到客户机的？这个能力集是怎么被查询、被填充的？
这篇文章就从纹理格式能力这个切面入手，把 Virgl 里能力查询与填充机制的完整链路梳理一遍。内容包括 Virtio-GPU 的能力查询命令、virglrenderer 侧的能力集填充逻辑、客户机 Mesa 驱动如何利用这些掩码，以及我在实际调试中踩过的一些坑。适合正在做虚拟化图形适配、排查虚拟机 OpenGL 兼容性问题、或者想理解 Virgl 内部设计的人阅读。
2. 为什么纹理格式能力在虚拟化里这么特殊
2.1 先理解 Virgl 的整体架构
Virgl 的完整链路可以拆成四层：
- 客户机应用层：调用 OpenGL API，比如
glTexImage2D。 - 客户机 Mesa 驱动（virgl driver）：把 GL 调用编码成 Virgl 命令流，写入 Virtio-GPU 的环形缓冲区。
- QEMU 的 virtio-gpu 设备：从环形缓冲区取命令，交给宿主机侧的 virglrenderer 库。
- virglrenderer：解码命令流，调用宿主机 OpenGL 实现（比如宿主机 Mesa、GPU 厂商驱动），真正把渲染做掉。
这四层里，纹理格式能力的问题是贯穿始终的。因为客户机里的 GL 应用会问“我能不能用 R16G16B16A16_FLOAT？我能不能用压缩纹理 BC7？”，这个问题的答案并不在客户机自身，而在宿主机 GPU 驱动手里。所以必须有一种机制，把宿主机的纹理格式支持情况“搬运”给客户机。
2.2 格式能力跟宿主机驱动强绑定
纹理格式的支持范围，跟宿主机 GPU 厂商、驱动版本、OpenGL 实现版本强相关。同样是 GL 4.5，A 卡和 N 卡在纹理格式上的支持可能差出一大截；同一张卡，驱动从 510 升到 535，可能就多出了好几组压缩纹理格式。
这就带来一个关键设计约束：客户机侧不能写死一份纹理格式清单，必须在启动阶段或渲染过程中动态向宿主机查询。查到的结果要能精确到一个格式一个格式地标记，这样上层 GL API 才能准确判断哪些纹理内部格式可用、哪些不可用、哪些需要回退到软件路径。
2.3 查询机制在 Virgl 里的位置
Virgl 的能力查询走的是 Virtio-GPU 的 capset 机制。每类能力（比如 GL、GL v2、GL v3、资源创建参数、格式修饰符）都对应一个 capability set，有独立的 ID 和版本号。客户机发起VIRTIO_GPU_CMD_GET_CAPSET命令，宿主机返回对应的能力数据块。
纹理格式能力就是这些 capability set 里的一块核心数据。它以位掩码（bitmask）数组的形式存在，每一位对应一个 Virgl 格式枚举值，0 表示不支持，1 表示支持。这个掩码的生成、传输、解析和填充，就是本文要拆解的主线。
3. 能力查询的完整链路：从客户机命令到宿主机响应
3.1 客户机侧的命令发起
在客户机 Mesa 里，virgl 驱动初始化时会对宿主机发起能力查询。代码路径大致是从virgl_init_screen开始，构建一个virgl_hw_query结构体，然后调用virgl_send_query之类的内部函数，把这个查询请求封装成 Virtio-GPU 命令，写入命令缓冲。相关结构体在 Mesa 源码src/gallium/drivers/virgl/virgl_hw.h里能看到，核心字段包括：
struct virgl_hw_query { uint32_t type; // 查询类型 uint32_t id; // 能力集 ID uint32_t query; // 查询内容 uint32_t result; // 返回结果 };这里type可以是VIRGL_QUERY_TYPE_CAP_SET，id对应能力集的编号，query不知道具体查哪个子项。客户机侧的逻辑很简单：把结构体填好，塞进命令流，然后等宿主机把结果写回来。
需要注意的是，Mesa virgl 驱动在发起查询时，会同时申明自己期望的能力集版本号。这个版本号跟 virglrenderer 的版本是对应的。版本不匹配时，宿主机可能返回错误，或者客户机解析能力数据时出现越界。这是后面排查问题的一个重要关注点。
3.2 virtio-gpu 设备的中转处理
命令到达 QEMU 的 virtio-gpu 设备后，设备层会根据命令类型做分发。对于VIRTIO_GPU_CMD_GET_CAPSET，QEMU 会调用 virglrenderer 提供的接口。核心函数原型大致如下：
int virgl_renderer_get_cap_set(uint32_t set_id, uint32_t version, const void **caps_data, size_t *caps_size);set_id是能力集编号，version是版本号，caps_data是返回的能力数据指针，caps_size是数据长度。QEMU 拿到这段数据后，会把它拷贝到 virtio-gpu 设备的能力缓冲区，再通过 PCI BAR 映射或 control queue 返回给客户机。
这一层有几个关键的判断逻辑：
- 如果
set_id超出 virglrenderer 已知的能力集范围，直接返回错误。 - 如果
version比当前实现的支持版本高，返回错误，避免客户机解析到格式不兼容的数据。 - 如果能力数据为空，返回错误，上层会走 fallback 逻辑。
QEMU 本身不关心能力数据的内部结构，它只做搬运。真正负责生成数据的，是 virglrenderer 侧。
3.3 宿主机侧的能力集数据生成
virglrenderer 启动时，会初始化一个全局的 capability 集合。这个集合在初始化阶段就决定了——它会调用宿主机 GL API（比如glGetIntegerv、glGetString）去探测当前 OpenGL 实现支持的特性，然后根据探测结果填充各个能力集的数据。
能力集的填充逻辑分散在 virglrenderer 的多个源文件里。比如virglrenderer.c里有总的caps入口函数，格式相关的填充在vrend_renderer.c里。函数内部会根据 GL 版本、GLSL 版本、扩展支持情况，逐一设置能力字段。纹理格式掩码的填充，通常是在获取 GL 上下文之后、渲染流程开始之前完成。
这个过程可以类比成：客户机问宿主机“你这儿有什么纹理格式”，宿主机先在启动时盘点了一遍自家仓库里的货，然后客户机来问的时候，直接把盘点表拍给对方。
4. 纹理格式掩码的填充机制深度拆解
4.1 格式枚举与掩码位的对应关系
Virgl 定义了一套完整的格式枚举VIRGL_FORMAT_*，从VIRGL_FORMAT_B8G8R8A8_UNORM到VIRGL_FORMAT_ASTC_*，数量大致在 100 到 200 之间，并且跟着 Mesa 的格式列表演化，几乎每个新 Mesa 版本都可能增加几个。
掩码数组的设计是按 32 位为一组。假设共有 152 个格式枚举值，那么就需要 152 / 32 = 5 个 uint32 变量，刚好凑一组。第 n 个格式的掩码位就是第n / 32个 uint32 的第n % 32位。
在 virglrenderer 的 capability 结构体里，掩码字段通常以bitmask开头命名，比如：
struct virgl_caps_v2 { uint32_t bitmask_1; // 格式 0-31 uint32_t bitmask_2; // 格式 32-63 uint32_t bitmask_3; // 格式 64-95 // ... };填充逻辑的核心，就是对每个格式枚举值调用宿主机 GL 的查询能力，判断该格式在当前 GL 实现上是否可用，然后把对应的位设为 1 或 0。
4.2 逐格式判定的关键函数
virglrenderer 在判断某个纹理格式是否支持时，会走一条“GL 格式映射 + 可用性探测”的路径。我理解的核心做法是：先把 Virgl 格式枚举映射到宿主机 GL 的 internal format、format、type 三个参数，然后调用探测函数。
伪代码大致如下：
static void vrend_update_format_bitmask(uint32_t *bitmask, enum virgl_format fmt) { GLenum internal_format, format, type; if (!vrend_format_to_gl(fmt, &internal_format, &format, &type)) return; // 无法映射，直接视为不支持 if (vrend_check_supported_format(internal_format, format, type)) { bitmask[fmt / 32] |= (1u << (fmt % 32)); } }其中vrend_check_supported_format内部会尝试用glTexImage2D创建一个最小的纹理，或者调用glGetInternalformativ查询 GL 实现是否接受这个组合。某些老驱动不支持glGetInternalformativ，这时候会回退到直接创建纹理再检查glGetError，不过这种方式成本高、有副作用，新代码基本都走glGetInternalformativ。
这里有一个容易踩坑的点：宿主机 GL 支持某个 internal format，不代表 Virgl 协议约定的 format/type 组合也会被宿主机接受。因为同一个 Virgl 格式，在不同 GL 版本下可以映射到不同的 internal format/format/type 三元组。如果映射表本身不匹配，掩码位可能会被错误地置为 1。
4.3 掩码填充的时机与懒加载
virglrenderer 并不是每次查询都重新探测一遍纹理格式。它会把探测结果缓存在全局变量里，第一次查询时触发一次全量探测，之后直接返回缓存数据。这样可以避免每一次GET_CAPSET都创建几十个纹理对象，性能会好很多。
不过缓存也带来一个问题：如果宿主机 GL 上下文发生变化（比如 EGL 掉线重建），缓存不会自动失效。我在实践里碰到过一种情况：宿主机的 GPU 驱动在渲染进程崩溃后自动重载，GL 能力实际上变了，但 virglrenderer 的格式掩码还是老数据，导致客户机拿着旧能力去请求格式，结果渲染异常。在较新版本的 virglrenderer 里，这类状态会在上下文重建时一并刷新，但如果你在维护旧版本分支，需要特别注意这个隐患。
4.4 能力集版本对格式内容的影响
virglrenderer 的 capability set 是区分版本的。比如VIRGL_CAPSET_GL是老版本，VIRGL_CAPSET_GL_V2引入了更多能力字段，VIRGL_CAPSET_GL_V3又进一步细化了资源创建参数和格式修饰符。
不同版本的能力集，纹理格式掩码的存放位置可能不同。低版本的能力集只覆盖早期的格式枚举，新格式（比如 ASTC、某些 YUV 格式）必须查高版本能力集才能拿到。客户机 Mesa 在初始化时会根据自己的代码版本，选择能支持的最高能力集版本去查询。如果客户机 Mesa 很新、宿主机 virglrenderer 很旧，就会出现高版本能力集返回失败、低版本能力集又没有新格式的情况，最终表现为虚拟机里某些纹理格式不可用。
5. 格式能力下发后的实际使用场景
5.1 纹理上传路径里的格式校验
客户机 Mesa 拿到纹理格式掩码之后，一个典型用途是在纹理上传路径里做校验。当应用调用glTexImage2D上传纹理时，Mesa 的状态跟踪器（state tracker）会走到纹理资源创建逻辑，virgl 驱动在virgl_texture_create里会检查目标格式在掩码里的位：
bool virgl_tex_format_supported(uint32_t format_bitmask, enum virgl_format fmt) { return (format_bitmask >> fmt) & 1u; }如果掩码位为 0，驱动会返回创建失败，上层状态跟踪器再尝试走软件路径或者直接报错。这个校验避免了对宿主机已明确不支持的格式做无效传输，节省了命令流带宽和宿主机侧的无效尝试。
5.2 格式修饰符与纹理导入
较新的 Virgl 能力集加入了格式修饰符（format modifier）的查询。格式修饰符是 DRM 子系统和 Vulkan 里常用的概念，用来描述纹理在显存里的排布方式（比如 X 方向压缩、Y 方向间隔等）。Virgl 通过格式修饰符能力，可以让客户机在导入外部纹理（如 DMA-BUF）时，选择宿主机真正支持的排布方式。
在这个场景里，纹理格式掩码的作用是“粗筛”：先看格式是否支持，再看格式修饰符组合是否支持。格式掩码为 0 的组合，后面的修饰符匹配就不用做了，直接判定不支持，省掉一轮更复杂的检查。
5.3 渲染状态切换里的格式匹配
Virgl 在执行渲染命令时，帧缓冲的格式必须与宿主机 GL 容器的格式匹配。如果客户机提交了一个宿主机掩码里为 0 的渲染目标格式，virglrenderer 侧的帧缓冲创建会失败，导致后续的 draw 命令全部异常。
因此，在客户机驱动做glFramebufferTexture相关的格式匹配时，也会参考格式掩码来提前规避不支持的组合。这块逻辑在 mesa 的st_framebuffer层和 virgl 驱动里都有涉及。
6. 常见问题与排查实录
6.1 掩码位与格式枚举对不上
症状：客户机创建的某个格式纹理，在宿主机渲染时格式错乱，或者直接被 virglrenderer 拒绝。
排查思路：
- 确认客户机 Mesa 与宿主机 virglrenderer 的版本兼容性。旧 virglrenderer 的格式枚举表和新 Mesa 不对齐时，同一个格式枚举值可能对应不同的 GL internal format。
- 打开 virtio-gpu 的调试日志，查看宿主机返回的能力集数据 hex dump，手动换算掩码位，确认是否跟客户机驱动的预期一致。
- 在宿主机上用
glGetInternalformativ手动验证对应的 GL 组合是否真的支持。
6.2 能力集版本不匹配导致查不到格式
症状：客户机里某些新格式（如 ASTC、P010）始终不可用，应用报 GL 错误或 texture 创建失败。
排查思路：
- 在客户机里用
dmesg或调试工具查看 virgl 驱动实际请求的能力集 ID 和版本。 - 在宿主机侧查看 virglrenderer 启动日志里注册的能力集版本号。
- 如果两端对齐不了，优先升级宿主机 virglrenderer，它保持向后兼容的能力通常比 Mesa 新版本更好。
6.3 掩码填充但实际纹理创建失败
症状：掩码位明明是 1，但真正创建指定格式纹理时，宿主机 GL 报错。
原因通常有两个：
glGetInternalformativ返回支持，但实际创建纹理时给定的 format/type 组合不在支持列表内。这属于 Virgl 格式映射表的 bug。- 宿主机 GL 延迟报错。某些驱动在校验内部格式时不会在
glTexImage2D立即报错，而是在后续的glTexSubImage2D或 draw 阶段才暴露。
排查时可以先用一个最小测试程序，在宿主机上直接调用 GL 接口创建该格式纹理，排除 Virgl 层的影响。
6.4 常见问题速查表
| 问题现象 | 可能原因 | 快速定位方法 | 解决建议 |
|---|---|---|---|
| 新格式在虚拟机里不可用 | 能力集版本太旧 | 对比双端版本号 | 升级 virglrenderer |
| 纹理创建乱码 | 格式枚举映射错位 | hex dump 能力集数据 | 对齐 Mesa/virglrenderer 版本 |
| 掩码位为 1 但创建失败 | GL 格式映射表有误 | 宿主机最小程序验证 | 修正映射表或改掩码 |
| 能力集返回空数据 | capset 版本超标 | 查看 virglrenderer 日志 | 降低客户机请求版本 |
| 上下文重建后能力异常 | 格式掩码缓存未刷新 | 重启虚拟机复现 | 更新补丁或强制重建缓存 |
7. 调试能力查询问题的实用技巧
7.1 在宿主机侧抓 capset 数据
virglrenderer 开启调试环境变量后，会打印能力集相关的日志。比如VIRGL_LOG_LEVEL=debug，在虚拟机启动时就能看到类似下面的输出：
VIRGL: caps set 2 version 1 size 256 VIRGL: bitmask_1 = 0xffffffff VIRGL: bitmask_2 = 0x7fffffff拿到掩码数据后，可以写一个小脚本按位解析，把置 1 的格式编号映射成格式名称，然后跟宿主机实际支持情况做对比。这一步能快速判断是掩码生成问题还是客户机解析问题。
7.2 在客户机侧验证解析结果
客户机 Mesa 里可以通过环境变量输出 virgl 驱动的初始化信息。在 X11 环境可以用EGL_LOG_LEVEL=debug，在直通测试里可以用LIBGL_DEBUG=verbose。这些日志会显示 virgl 驱动把能力集解析成了什么样的屏幕参数。
更直接的办法是用eglinfo或者glxinfo查看客户机里的 GL 渲染器字符串和扩展列表。如果渲染器字符串里的版本号跟宿主机能力不匹配，大概率是 capset 解析路径出了问题。
7.3 最小复现用例的构建
排查纹理格式问题时，我一般会在客户机里跑一段最小的 OpenGL 代码，只创建一个目标格式的纹理，不做其他渲染。比如：
GLuint tex; glGenTextures(1, &tex); glBindTexture(GL_TEXTURE_2D, tex); glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA16F, 1024, 1024, 0, GL_RGBA, GL_HALF_FLOAT, NULL); printf("glGetError: 0x%x\n", glGetError());然后在宿主机上跑同样的代码，逐一对比两边的glGetError。这样可以先确认是 Virgl 层的问题，还是宿主机驱动程序本身的问题。
7.4 版本对齐是绕不开的基本功
说实话，Virgl 项目迭代很快，Mesa 平均几个月就加一批新格式、新枚举，virglrenderer 的适配通常跟着 Mesa 跑。凡是做 Virgl 相关开发的，一定要把“双端版本锁定”当成基本操作。生产环境里能少动就少动，升级主版本前先在测试环境跑一轮格式兼容性用例，比出了问题再救火轻松得多。
根据我个人在实际排查中的经验，这类问题的故障面通常不大，九成以上都出在版本不匹配、格式映射表不同步、能力集索引越界这几个点上。养成“先查版本、再查掩码、最后查 GL 后端”的排查顺序，能少走很多弯路。
