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

在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指定配置文件路径。

3. 环境变量调整：设置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初始化过程