为什么你的屏幕会花屏?读懂Adreno-Tools-Drivers里的UBWC与u_gralloc补丁
为什么你的屏幕会花屏?读懂Adreno-Tools-Drivers里的UBWC与u_gralloc补丁
Adreno-Tools-Drivers 是一个把 Mesa 的 Turnip(freedreno)Vulkan 驱动定期打包成 Android 驱动包的开源项目。如果你给骁龙设备安装 Turnip 驱动后出现整屏花屏、画面错位或彩色条纹,大概率是 UBWC 压缩缓冲格式没被正确识别导致的。这篇文章带你读懂项目里最关键的 UBWC 与 u_gralloc 补丁,搞清花屏是怎么来的、又是如何被修掉的 🔍
一、Adreno-Tools-Drivers 项目速览:两周一版 Turnip 驱动 📦
这个项目本身不是一个庞大的代码库,而是一套"构建 + 补丁"工作流:
- build_turnip.sh:核心构建脚本,在 Linux 环境下用 Android NDK 编译 Mesa,产出可被 adrenotool 安装的
libvulkan_freedreno.so驱动包,并通过 GitHub Actions 每两周自动发版; - 根目录与 patches/ 目录下的系列补丁:针对新一代 Adreno GPU(A810/A825/A829/A830 等)和特定机型(如 Quest 3)的适配修复。
项目思路见 README.md:把官方驱动源码 + 一批"修花屏、通 GPU"的补丁 → 打包 → 定期发布,让普通用户无需自己编译就能用上最新的开源 Vulkan 驱动。
二、花屏原理:UBWC 压缩格式为什么没被识别?
2.1 UBWC 是什么
UBWC(Universal Bandwidth Compression) 是高通 Adreno GPU 的带宽压缩技术:像素数据不是按行顺序老老实实存放,而是按"瓦片"压缩后写入内存,可以显著降低显存带宽占用、提升游戏帧率。
但压缩有个前提——读写双方必须知道数据是压缩的。在 Linux 图形栈里,这个"知不知道"靠的是 DRM 格式修饰符(modifier):
DRM_FORMAT_MOD_QCOM_COMPRESSED:这块缓冲用了 UBWC 压缩;DRM_FORMAT_MOD_LINEAR:普通线性排布。
2.2 一个修饰符,决定了画面是正常还是"马赛克"
打个比方:UBWC 缓冲像一本特殊装订的书,页码排布和普通书完全不同。如果 Turnip 驱动被告知"这是普通书",却按普通书的页码去读一本压缩装订的书,每一页读出来的都是错位的像素——结果就是你看到的花屏、色块和条纹。
补丁提交说明里描述得很直接:"This caused huge distorted picture on the screen because the allocated buffer never got a proper modifier"(分配到的缓冲从未获得正确的修饰符,导致屏幕上出现巨大变形画面)。
三、u_gralloc 补丁详解:magic 检测失效与修复方案
3.1 u_gralloc 是谁
u_gralloc 是 Mesa 中的 Android gralloc 工具库,负责"翻译"系统分发的图形缓冲(SurfaceFlinger 创建的窗口缓冲就是由厂商 gralloc 分配的)。Turnip 在往窗口上画东西之前,必须先通过它弄清缓冲的格式、步长和修饰符。
3.2 旧逻辑:靠 "gmsm" 魔法值认人
旧代码的识别策略是:检查缓冲句柄里是否带有一个 "gmsm" 魔法值(magic),如果匹配,就认为这块缓冲由高通厂商 gralloc 分配,再去读取 UBWC 标志位、设置正确的修饰符。
问题在于:新版 gralloc 已经不写这个 magic 了。判断条件永远不成立 → 修饰符设置逻辑被整体跳过 → UBWC 缓冲被当作线性缓冲处理 → 整屏花屏。
3.3 修复思路:跳过"认人",直接查标志位
补丁的核心动作就两步(属于典型的 HACK 式修复,作者也在标题里注明了):
- 注释掉失效的
gmsmmagic 检查; - 对所有缓冲直接读取 UBWC 标志位(
0x08000000位),据此在DRM_FORMAT_MOD_QCOM_COMPRESSED和DRM_FORMAT_MOD_LINEAR之间设置修饰符。
这个补丁在仓库的多个补丁集中都以第 2 个 commit 的形式出现:
- tu_gen8.patch:面向 Adreno 8xx gen2 的 8 连补丁;
- tu8_kgsl_26.patch:面向 kernel 6.6 的 KGSL 的 10 连补丁;
- patches/tu_gen8_clean.patch:整理清理过的 9 连补丁。
顺带一提,构建脚本里还有一处配合改动:build_turnip.sh 用
sed修改了u_gralloc_fallback.c的句柄类型定义——因为项目在android-stub模式下编译(见 build_turnip.sh 中的-Dandroid-stub=true),类型转换要手工补上,这属于编译层面的适配,与花屏本身无关。
四、UBWC_5 / UBWC_6 补丁:新 GPU 也需要被"翻译" 🧩
光修 u_gralloc 还不够。内核驱动(KGSL)会把当前 GPU 支持的 UBWC 版本报告给用户态,但旧版接口头文件只定义到 KGSL_UBWC_4_0。新一代 Adreno GPU 会上报版本 5 和 6,而驱动代码里没有对应的处理分支。
补丁的做法很简洁:既然新的枚举值与旧值"逐一对应"(#defines map 1:1),直接在 switch 里补上 case 5 和 case 6,复用 8 通道宏瓦片(8-channel macrotile)配置即可:
- 补丁位置一:tu_gen8.patch
- 补丁位置二:tu8_kgsl_26.patch
这样一来,新 GPU 上报更高的 UBWC 版本时,Turnip 依然能拿到正确的瓦片布局参数,从源头避免格式误判。
五、补丁文件导航:每个补丁管什么?
| 文件 | 作用 |
|---|---|
| tu8_kgsl_26.patch | 主线 10 连补丁:UBWC_5/6 支持、u_gralloc 花屏修复、A810/825/829/830 启用等 |
| tu_gen8.patch | Adreno 8xx 的 8 连补丁(含同名 UBWC 与 u_gralloc 补丁) |
| patches/tu_gen8_clean.patch | 整理版 9 连补丁 |
| patches/quest3.patch | Quest 3(Adreno 740)完整启用,含 enable_tp_ubwc_flag_hint 等 UBWC 相关提示位 |
| patches/force_sysmem_no_autotuner.patch | 强制使用 sysmem 渲染,规避 GMEM 缓存引发的兼容问题 |
| patches/vk_sync_timeline.patch | 基于 timeline 的 Vulkan 队列同步原语 |
| 39751.patch | KGSL profiling 逻辑简化 + timeline 同步改造 |
| build_turnip.sh | 一键构建脚本,产出 adrenotool 驱动包 |
六、花屏排查清单:4 步定位问题 ✅
遇到 Turnip 花屏,可以按下面的顺序自查:
- 先升级驱动包——大多数花屏问题就是 u_gralloc 这类补丁修复的,确认 adrenotool 里装的是最新一版;
- 确认 GPU 型号已被识别——查看日志中 GPU 是否被映射到正确的
GPUId,未识别的芯片会走错误的默认配置; - 对比系统 gralloc 版本——系统 OTA 后厂商 gralloc 变化可能让旧补丁失效,需要更新驱动包;
- 尝试关闭 GMEM——个别芯片(如 A810/A829)用 GMEM 缓存会挂起,补丁通过
disable_gmem属性强制走 sysmem 路径,见 tu_gen8.patch。
七、本地构建指南:自己打一个 Turnip 驱动包
如果不想等两周一版的自动发布,也可以本地构建(需要 Linux 环境):
git clone https://gitcode.com/gh_mirrors/ad/Adreno-Tools-Drivers
cd Adreno-Tools-Drivers
bash ./build_turnip.sh
脚本会自动检查依赖(git、meson、ninja、NDK 等,见 build_turnip.sh)、下载 NDK、克隆 Mesa 源码并完成交叉编译,最终生成含 libvulkan_freedreno.so 与 meta.json 的 zip 驱动包,交给 adrenotool 安装即可。
写在最后
花屏看似玄学,本质往往只是"一块压缩格式的缓冲被当成了线性缓冲"。读懂 Adreno-Tools-Drivers 里的 UBWC 与 u_gralloc 补丁,你不仅理解了花屏的来龙去脉,也掌握了一套"用最小改动修复驱动层问题"的思路——这正是开源 Vulkan 驱动社区持续把 Adreno 体验打磨得越来越稳的底气 💪