首页
/ 解决ossia/score项目在Raspberry Pi 5上的EGLFS显示问题

解决ossia/score项目在Raspberry Pi 5上的EGLFS显示问题

2025-07-10 13:02:31作者:翟萌耘Ralph

在ossia/score项目的开发过程中,团队遇到了在Raspberry Pi 5平台上EGLFS(Embedded Graphics Library Framebuffer System)显示功能失效的问题。本文将详细分析问题的原因和解决方案。

问题背景

EGLFS是Qt框架提供的一个平台插件,专门为嵌入式系统设计,可以直接使用OpenGL ES进行渲染而无需完整的窗口系统。在Raspberry Pi这样的嵌入式设备上,EGLFS通常通过KMS(Kernel Mode Setting)和DRM(Direct Rendering Manager)子系统与硬件交互。

问题现象

开发团队最初观察到以下错误现象:

  1. 当尝试使用EGLFS时,系统报告"drmModeGetResources failed (Operation not supported)"
  2. 随后尝试通过配置文件指定DRM设备后,出现"Could not initialize egl display"错误
  3. 设置QT_QPA_EGLFS_INTEGRATION=none环境变量后,又出现"EGL Error : Could not create the egl surface: error = 0x300b"错误

根本原因分析

经过深入调查,发现问题主要由两个因素导致:

  1. 缺失关键开发包:在构建SDK时缺少mesa-libgbm-dev包,导致eglfs_kms插件未能正确构建。这个插件是Qt与KMS/DRM子系统交互的关键组件。

  2. 驱动加载问题:即使插件可用,系统仍无法正确加载MESA驱动(vc4_dri.so、kms_swrast_dri.so和swrast_dri.so),导致无法创建GBM设备。

解决方案

开发团队通过以下步骤解决了问题:

  1. 确保插件构建:在SDK构建环境中添加mesa-libgbm-dev依赖,确保eglfs_kms插件能够正确构建。

  2. 配置DRM设备:创建eglfs.json配置文件,明确指定使用/dev/dri/card1设备:

{
  "device": "/dev/dri/card1"
}

并通过环境变量QT_QPA_EGLFS_KMS_CONFIG指定配置文件路径。

  1. 环境变量调整:设置QT_QPA_EGLFS_INTEGRATION=none,避免使用不兼容的集成方式。

技术细节

在Raspberry Pi 5上,视频输出通常由两个DRM设备控制:

  • /dev/dri/card0:通常对应VC4显示控制器
  • /dev/dri/card1:通常对应更高级的显示管线

GBM(Generic Buffer Management)是Mesa项目提供的一个API,用于在DRM设备上分配和管理图形缓冲区。它是EGLFS与底层图形硬件交互的关键组件。

结论

通过修复构建依赖和正确配置DRM设备,ossia/score项目成功解决了在Raspberry Pi 5上的EGLFS显示问题。这个案例展示了在嵌入式Linux系统上图形显示问题的典型排查思路:从构建环境检查开始,到运行时配置调整,再到驱动和硬件抽象层的验证。

对于其他开发者遇到类似问题时,建议按照以下步骤排查:

  1. 确认所有必要的开发包已安装
  2. 检查Qt平台插件是否完整构建
  3. 验证DRM设备配置
  4. 逐步调试EGL初始化过程
登录后查看全文