欢迎加入开源鸿蒙PC社区 https://harmonypc.csdn.net/欢迎在PC社区平台申请新建项目https://atomgit.com/OpenHarmonyPCDeveloper/欢迎加入开源鸿蒙PC社区Harmony PC 开发者社区欢迎在PC社区平台申请新建项目OpenHarmony PC Developer - 开源代码托管,代码协作 - AtomGit本文记录 Mesa 24.3.4.1.1 在 HarmonyOS PC AArch64 上的适配、Conan 制品交付和消费者验证。上游源码版本是 Mesa 24.3.424.3.4.1.1是本项目的 Conan 交付版本。测试数字只采用实际回报和日志中已经验证的口径不把未完成的跨平台测试写成全量通过。一、先看结论Mesa 是图形栈的核心项目涉及 EGL、GLES、GBM、OSMesa、Gallium 和多个软件渲染后端。HarmonyOS PC 适配的难点不只是把代码编译出来还要让共享库导出表、动态加载、无显示器软件渲染和 ELF 运行时约束同时成立。本轮交付的关键结果项目结果上游项目Mesa上游源码版本24.3.4Conan 交付版本24.3.4.1.1官方源码地址https://archive.mesa3d.org/mesa-24.3.4.tar.xz源码 SHA-256e641ae27...以配方和证据日志中的完整值为准目标平台HarmonyOS PC / AArch64分支fix/mesa-24.3.4.1.1PRMR #11116最新交付提交da7d9cfe95f7ac42746f271631593e35f3c17731交付状态PR 已更新并触发/rebuild以页面最终状态为准本轮最终修复集中在两个问题libdrm静态库通过link_whole被并入共享libEGL导致 137 个drm*符号泄漏到 EGL 导出表。llvm-nm将三个 libc weak-UND 符号按 4 字段输出触发egl-symbols-check的误报。最终使用正式交付补丁0011和0012conan create返回 0test_mesa、EGL 动态加载、GBM/EGL/GLES 消费者和 OHOS 专项测试均通过。图 1MR #11116 显示 Mesa 高难度交付已合入页面展示版本、分支、测试统计和审核状态。二、Mesa 在图形栈中的位置可以把本次适配理解为下面这条链路Mesa 源码 - Meson 构建 EGL/GLES/GBM/OSMesa/Gallium - Conan 配方打包 include/ lib/ bin/ - ohpcd 制品仓发布 mesa/24.3.4.1.1 - 下游通过 EGL/GLES/GBM 或 OSMesa 消费 - HarmonyOS PC 上动态加载、渲染并运行这里有三个容易混淆的版本号名称含义mesa-24.3.4官方上游 tarball/tag 的源码版本mesa/24.3.4.1.1本项目 Conan 配方使用的交付版本fix/mesa-24.3.4.1.1AtomGit 交付分支Conan 版本增加修订号不代表伪造了一个上游 Mesa 版本它用于承载 HarmonyOS PC 的配方、补丁和制品修订。三、为什么这是高难度适配3.1 共享 EGL 的导出表不是“能链接”就结束Mesa 的libEGL会链接多个静态和共享组件。在本项目中libdrm通过link_whole进入链接闭包。普通链接成功只能说明符号能被解析却不能说明共享库的公开导出表符合 EGL 的接口边界。第一次检查时egl-symbols-check发现 137 个drm*符号从libEGL泄漏出去。这个问题会带来两个风险下游可能误以为这些 DRM 符号是 EGL 的稳定公开 API同名符号与系统libdrm或其他图形组件发生意外绑定。3.2 weak-UND 符号会造成测试误报egl-symbols-check使用llvm-nm检查导出符号。HarmonyOS libc 中的pthread_mutexattr_destroy、pthread_mutexattr_init、pthread_mutexattr_settype以 weak-UND 形式出现llvm-nm的输出字段形态与检查脚本默认假设不同。这三个符号不是 Mesa 把错误 API 导出到 EGL而是平台 libc 的弱未定义引用。如果不区分 weak-UND 和真实导出检查会把平台 ABI 特征误报成 Mesa 导出错误。3.3 图形库必须面对无显示器环境HarmonyOS PC 适配不能假定存在 X11、Wayland 或真实 DRM 设备。Mesa 的软件渲染路径、EGL surfaceless、GLES 最小调用和 OSMesa 离屏上下文是更适合在设备上验证的路径。本轮消费者验证覆盖eglInitialize、eglQueryString、GLES2 调用、OSMesa 固定管线以及 GBM/EGL/GLES 公开头文件的编译链接。它们验证的是可消费性不等价于真实 GPU 驱动或窗口系统已经支持。四、难度拆解Mesa 为什么不是普通 C/C 库适配很多库的 HarmonyOS PC 适配只需要解决“编译器不认识某个宏”“缺一个头文件”或“测试 ELF 需要签名”。Mesa 不一样它是一个把图形 API、动态链接 ABI、软件渲染器、硬件驱动接口、编译器工具链和窗口系统适配层组合在一起的图形栈。一个库的构建成功并不代表另一个层面的接口边界正确。4.1 难点一一个源码树同时生成多类用户可见库本次包不只生成一个libmesa.so。交付物中至少涉及组件下游用途验证重点libEGL.so.1上下文、显示连接、surfaceless 初始化SONAME、动态加载、导出符号表libGLESv2.soGLES2 渲染 API公开头文件、链接和运行时依赖libGLESv1_CM.so兼容固定管线接口包内布局和消费链路libgbm.so.1图形缓冲区管理接口gbm.h、pkg-config、链接边界libOSMesa.so.8无窗口系统离屏软件渲染上下文创建、像素缓冲区和 GL 版本这意味着“一个二进制跑起来”不够。任何一个组件遗漏安装、SONAME 错误、导出表污染或运行时加载到系统同名库都会让下游得到错误的结论。因此文章必须同时给出制品内容图、SONAME 图和真实dlopen图。4.2 难点二Meson 交叉编译和图形依赖不是普通静态链接Mesa 使用 Meson 构建且依赖链中包含 LLVM、libdrm、expat 以及生成阶段的 bison/flex/m4。这里同时存在 build-machine 工具和 host-machine 图形库构建机工具bison / flex / m4 目标机库libdrm / LLVM / expat / Mesa EGL-GLES-GBM 运行时组件Gallium driver / libEGL / libGLAPI / 系统 libc如果把这些角色混在一起常见结果是“配置阶段找到的是宿主工具运行时加载的是目标库的错误版本”或者 Conan 根据 ABI 计算出另一个 package ID。本次真机安装时必须固定OHOS / armv8 / clang 15 / C17 / libc正是为了让消费者获得与已发布 Mesa 包相同的二进制身份。4.3 难点三共享库 ABI 比链接成功更严格静态库通过link_whole进入共享库时链接器并不会自动判断哪些符号应该成为对外 ABI。libEGL在修复前泄漏 137 个drm*符号就是典型例子生成libEGL.so没有失败dlopen也未必立即失败但共享库已经暴露了不应公开的实现细节。这类问题难在它通常只会被符号质量门禁或复杂下游发现。为此本项目把检查从“库是否存在”提升为共享库文件存在 - SONAME 正确 - EGL 声明 API 存在 - 静态 libdrm 内部符号不泄漏 - dlopen 和 eglInitialize 可运行--exclude-libs,ALL的意义也在这里它处理 ABI 边界而不是一次普通的编译兼容补丁。4.4 难点四平台工具行为会改变测试结论本轮不仅要面对 Mesa 自身代码还要面对llvm-nm、Meson、LLVM 工具链和 HMDFS 文件系统的行为差异。llvm-nm对 weak-UND 的输出字段形态使 EGL 符号检查把 libc 弱引用误判为非法导出HMDFS 对某些权限、缓存和临时文件操作的语义与常规 Linux 文件系统不同HarmonyOS PC 没有可假定存在的 X11、Wayland、/dev/dri或桌面 GPU 驱动路径SDK clang 在链接阶段会调用自身的 lld运行时还需要正确的 LLVM/libxml2 搜索路径。这些问题都不能靠把测试直接跳过解决。项目采用的是“明确平台边界 最小独立复验”的方式对 weak-UND 只忽略三项已经解释的符号对无 GPU 场景使用 surfaceless EGL 和 llvmpipe对 SDK linker 运行时缺库问题显式设置 SDK LLVM 库路径。4.5 难点五软件渲染成功与硬件驱动成功必须分开Mesa 的软件渲染路径可以在没有 GPU 驱动、没有显示服务器的条件下产生有效结果。图 5 的 EGL 1.5 初始化和llvmpipe/OSMesa 测试证明的是Mesa 包可加载 EGL API 可初始化 软件渲染路径可用 Conan 消费者能在真机运行它不证明以下结论真实 GPU 驱动已加载 X11/Wayland 已支持 DRM 设备节点可用 所有 Gallium 硬件后端均可用高难度适配的价值不是把结论写大而是精确划分“已经验证的软件栈能力”和“仍依赖设备图形基础设施的能力”。4.6 难点六上游测试规模大不能用一个通过率掩盖差异MR 页面记录的上游审查口径达到 3264 项。Mesa 测试不仅有普通单元断言还包括驱动专属、IR、缓存、反汇编、图像比较和平台工具依赖。OHOS 上某个 GTest 未完成可能是 HMDFS、GLSL IR、字节序、外部工具、后端模块或网络来源阻塞并不必然说明 EGL/GLES 基础链路损坏。因此本项目把测试结果拆成三层层次本轮回答的问题结论表达上游测试台账哪些原始测试和平台边界存在保留未完成项、首错和恢复条件包级门禁配方、补丁、共享 ABI、test_package 是否闭环conan create、符号检查和审计通过真机消费者发布制品能否被真实下游加载和调用dlopen、EGL 1.5、退出码 0只有三层都呈现读者才能区分“完成了软件图形栈可消费交付”和“尚未具备全部硬件驱动矩阵”。这也是 Mesa 适配相较普通库最容易被误报、也最需要严谨说明的地方。五、适配前的环境和源码固定5.1 固定官方源码配方使用官方 Mesa 归档地址https://archive.mesa3d.org/mesa-24.3.4.tar.xz适配前至少保存以下信息curl -fL -o mesa-24.3.4.tar.xz \ https://archive.mesa3d.org/mesa-24.3.4.tar.xz sha256sum mesa-24.3.4.tar.xz实际配方证据确认官方 URL 和e641ae27...源码摘要一致。发布文章时应把完整 SHA-256 从最终日志复制过来不要只保留省略值。5.2 目标配置本次构建以 OHOS AArch64 为目标核心设置为osOHOS os.version6.0 archarmv8 build_typeRelease compilerclang compiler.version15 compiler.cppstd17 compiler.libcxxlibc图 2真机终端显示 HarmonyOS、AArch64、Conan 2.29.1以及 clang 和 binary-sign-tool 的实际路径。Mesa 是 Meson 项目Conan 配方负责把目标编译器、工具链、依赖路径和安装布局传入构建过程。不要把服务器上的 Linux Mesa 包路径直接复制到真机最终验证必须从 Conan 包的include/、lib/和实际运行环境取得文件。5.3 依赖边界Mesa 可以包含很多可选驱动和窗口系统后端。HarmonyOS PC 本轮的验证重点是EGL 共享库及其 SONAMEGLESv1/GLESv2 公开接口GBM 接口和链接闭包OSMesa 软件渲染Gallium softpipe/llvmpipe 离屏路径OHOS 专项进程名和离屏渲染测试。X11、Wayland、真实 GPU 内核驱动、系统 DRM 设备等能力如果没有在设备上成立必须作为边界说明而不是从测试分母中悄悄删除。六、两项正式修复6.1 补丁 0011收敛libEGL的静态符号泄漏问题表现egl-symbols-check: drm* leaked symbols 137根因是libdrm静态库通过link_whole被整体带入共享libEGL。整体链接能保证内部符号可用但也可能把不属于 EGL 公开接口的符号带入动态导出表。解决方式是在libEGL的链接参数中增加-Wl,--exclude-libs,ALL这个选项不删除 EGL 自己的公开 API而是限制静态库成员符号向共享库外部导出。修复后检查结果从 137 个drm*泄漏降为 0。需要注意--exclude-libs,ALL是链接边界控制不是“把 libdrm 从 Mesa 删除”。EGL 内部仍可以使用所需实现只是不把静态依赖的内部符号伪装成 EGL 公共 API。6.2 补丁 0012处理平台 libc 的 weak-UND 检查误报问题表现是egl-symbols-check将三个 weak-UND 符号当作异常pthread_mutexattr_destroy pthread_mutexattr_init pthread_mutexattr_settype解决方式是在测试注册时增加三个明确的--ignore-symbol--ignore-symbol pthread_mutexattr_destroy --ignore-symbol pthread_mutexattr_init --ignore-symbol pthread_mutexattr_settype这不是把真实 EGL 符号检查关闭而是把已经确认属于平台 libc weak-UND 的三项从误报集合中排除。其他未列出的异常符号仍会让检查失败。两个补丁均已注册到conandata.yml并同步更新manifest.yaml和notes.md。它们不是只存在于执行端临时目录的测试副本Conan 干净创建时会实际应用。七、构建、打包和门禁在真机消费前先使用conan download mesa/24.3.4.1.1:* -rohpcd从ohpcd获取对应 OHOS AArch64 二进制包。下载输出中的 package ID、revision、sharedTrue和 ABI settings 是制品来源的可复核身份不应以本地源码构建目录替代。图 3真机从ohpcd获取 Mesa 二进制包输出包含 package revision、OHOS / armv8 / clang 15 / C17 / libc设置与共享库选项。典型的 Conan 构建入口如下conan create archives/m/mesa/24.3.4.1.1 \ -pr:hci/conan/profiles/ohos-aarch64 \ -pr:bci/conan/profiles/ohos-aarch64 \ -rohpcd \ --buildmissing \ -c tools.build:jobs8本轮conan create返回 0并在包内执行test_mesa。消费者输出包含GL_VERSION 4.5 Compatibility Profile Mesa 24.3.4 (llvmpipe) test_mesa ALL PASS构建门禁关注的不是单一退出码而是下面几项是否同时成立门禁关注内容本轮结果配方门禁源码、补丁、构建和打包逻辑完整通过conan create干净构建、安装和test_package通过EGL 符号检查drm*泄漏、weak-UND 误报通过泄漏 137→0消费者测试EGL/GLES/GBM/OSMesa 真实调用通过OHOS 专项softpipe 离屏渲染与进程名检查通过原子性审计仅 Mesa 白名单文件变化通过八、消费者验证证明包真的能用8.1 OSMesatest_packagetest_package/test.c通过 Conan 创建流程编译并运行实际调用OSMesaCreateContextExt、OSMesaMakeCurrent等公开 API并检查 OpenGL 版本。它验证的是 Mesa 包的头文件、库文件、链接关系和运行时加载而不是仅检查包目录是否存在。8.2libEGL.so.1动态加载另一个消费者使用dlopen和dlsymdlopen libEGL.so.1 - dlsym eglGetDisplay - dlsym eglInitialize - dlsym eglQueryString - surfaceless EGL/GLES2实际结果为dlopen OK并初始化出EGL 1.5。这一步尤其重要因为共享库的 SONAME 和动态加载路径是很多下游项目真正关心的接口。图 4从完整 package reference 定位缓存目录确认包内含libEGL、libGLESv1_CM、libGLESv2、libOSMesa和libgbm且libEGL的 SONAME 为libEGL.so.1。8.3 GBM/EGL/GLES 最小公开头消费本轮还分别使用 GBM、EGL、GLESv2 和 GLESv1_CM 的公开头文件编译最小程序并链接对应库。四项消费者均返回 0。它们证明了包的 include/lib 布局和公开链接关系但不声称设备存在真实 DRM 节点或 GPU 加速。8.4 OHOS 专项离屏测试OHOS 专项ohos_adapt_test覆盖进程名获取和 softpipe 离屏渲染运行结果为ALL PASS。该测试的价值是验证 Mesa 在没有窗口系统的 HarmonyOS 环境下仍可走软件渲染路径。图 5消费者程序编译成功后通过包内库路径dlopen libEGL.so.1在 surfaceless 软件渲染环境初始化 EGL 1.5并以退出码 0 结束。九、测试结果如何如实表达本轮没有宣称 Mesa 的全量 GTest 全部通过。证据中明确保留以下未完成项未完成集合数量原因边界util_testsCache7HMDFS 平台阻塞general_ir_test7上游 GLSL IR 差异valhall_disasm_test244反汇编器字节序/工具差异未实例化驱动 GTest未统一计数libclc、AMDGPU LLVM 模块或网络条件阻塞因此正确表述是当前 OHOS 配置下Mesa 核心包构建、EGL 符号质量门禁、Conan 消费者、EGL/GLES/GBM/OSMesa 最小验证和 OHOS 专项测试通过部分依赖特定 GPU 后端、反汇编工具、GLSL 行为或 HMDFS 语义的上游 GTest 保留未完成项及恢复条件。不应写成“Mesa 上游全部测试通过”或“所有 GPU 驱动均已适配”。十、常见失败与排查方法10.1drm*符号仍然泄漏先检查实际使用的libEGL.so.1.0.0是否来自当前 Conan 包再确认--exclude-libs,ALL已进入正式配方补丁并在干净conan create中应用。只在临时构建目录手工加链接参数不能作为交付修复。10.2egl-symbols-check报 pthread 符号先用llvm-nm查看符号类型和字段数确认是 libc weak-UND而不是 EGL 真正导出的强符号。只有确认属于这三个已知平台弱引用时才能使用对应的--ignore-symbol不能扩大忽略名单来掩盖新的符号污染。10.3dlopen libEGL.so.1失败检查三个方面libEGL.so.1的 SONAME 是否正确LD_LIBRARY_PATH或 rpath 是否指向 Conan 包的lib/依赖的 GLES、GLAPI、LLVM 或系统库是否来自同一套 ABI。本项目的质量警告明确要求下游使用显式包路径区分系统/lib64/libEGL.so不能让系统同名库抢先加载。10.4 为什么没有真实 GPU 画面本轮验证的重点是 HarmonyOS PC 上的可消费软件渲染和动态库接口。没有/dev/dri、真实 GPU 驱动或窗口系统时EGL surfaceless、OSMesa、softpipe/llvmpipe 仍然可以验证编译、链接、加载和离屏渲染这不等价于硬件加速已经启用。十一、截图证据说明本文已经按下面顺序嵌入图片。发布到 CSDN 时依次上传本目录对应 JPG并将本地相对图片链接替换为 CSDN 自动生成的在线链接PR 交付图显示 MR #11116、分支fix/mesa-24.3.4.1.1、最新提交和评审状态。真机环境图完整 HarmonyOS PC 桌面和终端显示uname -a、uname -m、conan --version。制品下载图显示conan download mesa/24.3.4.1.1:* -rohpcd成功以及osOHOS、archarmv8的包设置。包内消费者图显示 Conan 安装成功、conan cache path、libEGL.so.1或libOSMesa.so的实际路径。运行验证图显示eglInitialize EGL 1.5、OSMesa GL_VERSION ... llvmpipe、ALL PASS和退出码 0。截图中没有 token、密码、私钥或不必要的内网地址。发布时保留图注避免审核人员需要从终端内容自行推断每张图证明的结论。十二、可复用流程后续适配其他图形库时可以复用以下顺序固定官方源码 URL、版本和 SHA-256。列出需要交付的组件、共享库、SONAME 和公开头文件。先验证平台工具链和依赖制品是否可消费再开始大规模测试。将每个修复写入正式补丁、conandata.yml和 manifest禁止只改临时 build 目录。对共享库同时做链接、导出符号、SONAME、dlopen和真实 API 消费验证。区分软件渲染、窗口系统和真实 GPU 驱动能力不扩大测试结论。以conan create、test_package、OHOS 专项和 W3/W4 门禁作为交付闭环。文章中同时呈现 PR 事实、制品来源、真机路径和运行输出。十三、结语Mesa 24.3.4.1.1 的 HarmonyOS PC 适配重点不是“把 Mesa 编译出来”而是把图形栈的边界说清楚并验证清楚官方 Mesa 24.3.4 源码 - OHOS AArch64 Meson/Conan 构建 - libEGL 导出表收敛drm* 137 - 0 - weak-UND 平台误报修正 - Conan 制品安装 - EGL/GLES/GBM/OSMesa 消费 - surfaceless/llvmpipe 真机验证这条证据链证明的是Mesa 的核心共享库和软件渲染消费者可以在 HarmonyOS PC AArch64 上构建、打包、加载和运行平台专属 GTest、真实 GPU 驱动和窗口系统能力仍按日志中记录的边界保留。十四、FAQQ1为什么源码是 24.3.4Conan 却是 24.3.4.1.124.3.4 是上游源码版本24.3.4.1.1 是 HarmonyOS PC 适配后的 Conan 交付版本。后缀用于表达配方和补丁修订不改变上游源码身份。Q2为什么必须关注libEGL的导出符号共享库的导出表就是下游可见接口。静态依赖通过link_whole泄漏 137 个drm*符号会污染 ABI 边界甚至引发同名符号冲突。--exclude-libs,ALL用于收敛静态库内部符号。Q3--ignore-symbol会不会掩盖真实问题只有三个已经确认属于 HarmonyOS libc weak-UND 的符号被忽略其他符号仍由检查脚本校验。忽略项必须记录原因、来源和恢复条件不能用通配符关闭检查。Q4为什么dlopen要设置包的库路径系统可能已有同名/lib64/libEGL.so。显式设置 Conan 包的LD_LIBRARY_PATH或 rpath才能确认加载的是本次交付的 Mesa而不是系统库。Q5llvmpipe 通过是否代表 GPU 驱动通过不是。llvmpipe 是软件渲染器。本轮只证明软件渲染和图形 API 消费链路可用不宣称 Intel、AMD、NVIDIA 或其他硬件驱动已经完成适配。
