MIPI-DSI LCD 用户态内存图像显示 Demo
dsi_lvgl_colorbar 是一个 Linux 用户态的 LVGL + DRM 示例。应用在 CPU 内存中生成或接收像素数据,LVGL 将其渲染到 DRM GEM 显存,再由 VOP 经 MIPI-DSI 输出到 LCD。
当前默认内容为 8 色彩条,用于验证“用户态内存图像 → LCD”的完整通路。开发者可将彩条替换为 UI、解码图片、相机帧、算法结果或 FPGA/DSMC 读取的数据。
适用条件
- Linux 内核已启用 DRM、VOP、MIPI-DSI、DPHY、对应面板及背光驱动。
- DTS 已正确连接显示路由。Rockchip 平台通常需启用对应的
route_dsi:
&route_dsi {
status = "okay";
};
- 板端存在
/dev/dri/card0,并可在/sys/class/drm/看到已连接的 DSI connector。 - 应用运行期间,DRM primary plane 不被其他图形程序占用。
不同板型、面板和 SDK 的 DTS 节点名称、connector 名称和原生分辨率可能不同,须以运行时 DRM 信息为准,不能照搬示例数值。
已验证设备树
完整 DTS 已随本工程保存:dts/rk3506g-evb1-v10-dsmc-master.dts。它包含 DSMC、32 MiB CMA、DSI/DPHY/VOP/route、LCD 3.3 V 电源和面板电源引用的全部板级覆盖。具体配置、安装方法和移植限制见 dts/README.md。
该 DTS 仅适合当前 RK3506G EVB1 V10 + DSMC 转接板 + 已验证 LCD。移植到其他板卡时,必须重新确认 DSMC 映射及 DQS DLL、面板电源 GPIO、面板时序和 DSI lane rate。
目录结构
| 路径 | 用途 |
|---|---|
src/dsi_lvgl_colorbar.c | 示例应用入口;创建 LVGL 彩条或项目自定义内容。 |
src/lvdrm_drm_rockchip.c | Rockchip DRM 输出后端;负责 GEM 显存、双缓冲、plane 选择与提交。一般不需要修改。 |
src/dsmc_demo.c | DSMC LocalBus 读写与带宽测试工具。(未通过测试) |
src/dsi_image_demo.c | 早期 DSI 显示测试程序。 |
src/rockit_vo_demo.c | Rockit VO API 测试程序。 |
scripts/run_dsi_lvgl_colorbar.sh | 独占运行启动器;会停止 rk_demo 后再启动彩条。可按项目实际图形程序名称修改。 |
build/ | make 生成的可执行文件;可随时用 make clean 删除并重新构建。 |
images/ | 当前用于测试的 boot 镜像,不参与用户态程序编译。 |
dts/rk3506g-evb1-v10-dsmc-master.dts | 当前已验证的完整 DSMC + MIPI-DSI 板级 DTS。 |
dts/README.md | DTS 中每项板级配置、安装与移植限制。 |
Makefile | 交叉编译规则。 |
数据路径:输入帧/CPU 内存 → LVGL 绘制缓冲 → DRM GEM 双缓冲 → VOP plane → MIPI-DSI → LCD。
编译
在 Linux 主机的 Demo 目录执行:
cd /path/to/dsmc_fpga_demo
make dsi_lvgl_colorbar
生成文件为 build/dsi_lvgl_colorbar。Makefile 中的 CROSS、LVGL_SYSROOT 和 LVDRIVERS_SRC 必须指向当前项目实际使用的 SDK 工具链、Buildroot sysroot 和 lv_drivers 源码。
若板端 LVGL、libdrm 或内核 DRM 接口与编译 sysroot 不匹配,应用可能无法启动;应使用与目标 rootfs 同一 SDK 构建产物。
部署与启动
可使用 U 盘、scp、NFS、升级包或 ADB 将以下两个文件放到板端临时目录,例如 /tmp:
build/dsi_lvgl_colorbarscripts/run_dsi_lvgl_colorbar.sh
使用 ADB 时,在主机执行(将 <serial> 替换为目标板序列号):
adb -s <serial> push build/dsi_lvgl_colorbar /tmp/dsi_lvgl_colorbar
adb -s <serial> push scripts/run_dsi_lvgl_colorbar.sh /tmp/run_dsi_lvgl_colorbar.sh
adb -s <serial> shell
进入目标板 shell 后,直接执行:
mkdir -p /userdata/bin
cp /tmp/dsi_lvgl_colorbar /userdata/bin/
cp /tmp/run_dsi_lvgl_colorbar.sh /userdata/bin/
chmod 0755 /userdata/bin/dsi_lvgl_colorbar
chmod 0755 /userdata/bin/run_dsi_lvgl_colorbar
/userdata/bin/run_dsi_lvgl_colorbar
```xia
启动器默认停止 `rk_demo`,用于避免演示程序争用 DRM primary plane。若目标系统运行其他 GUI、Wayland/Weston 或自研 DRM 程序,应在启动本 Demo 前停止对应程序,或改用不会冲突的 DRM overlay plane。
按 `Ctrl-C` 退出;也可向进程发送 `SIGTERM`。
## 验收
运行时,LCD 应持续显示 8 色竖向彩条。另开一个板端 shell,执行:
```sh
pidof rk_demo || echo rk_demo-not-running
cat /sys/class/drm/card0-DSI-1/enabled
grep "win1-0" /sys/kernel/debug/dri/0/summary
dmesg | grep -c "dcs cmd: -110"
当前 RK3506 EVB1 实测预期:
rk_demo-not-running;- DSI connector 为
enabled; - VOP 显示窗口显示
ACTIVE; dcs cmd: -110计数为0。
其他平台中 connector 可能不是 card0-DSI-1、窗口也不一定叫 win1-0。先执行 ls /sys/class/drm/ 与 cat /sys/kernel/debug/dri/0/summary,再替换为实际名称。
二次开发流程
1. 明确输入帧协议
无论图像来自文件、网络、摄像头还是 DSMC/FPGA,先明确以下参数:
| 参数 | 必须确认的内容 |
|---|---|
| 宽高 | 源图像 width、height,以及面板原生模式。 |
| 像素格式 | RGB888、BGR888、RGB565、ARGB8888、YUV 等。 |
| stride | 每行有效字节数;可能大于 width × 每像素字节数。 |
| 帧率 | 更新频率和允许的端到端延迟。 |
| 所有权 | 谁写源帧、谁读源帧,以及帧完成通知机制。 |
不能假设源图像的宽高、颜色顺序或行跨度与 LCD 一致。格式或 stride 错误通常表现为偏色、斜纹、画面错行或闪烁。
2. 保持 DRM 后端不变
保留以下初始化、主循环和清理流程:
lv_init();
drm_disp_drv_init(0, 0, 0);
while (keep_running) {
lv_timer_handler();
usleep(1000);
}
drm_disp_drv_deinit();
lv_deinit();
drm_disp_drv_init(0, 0, 0) 会选择 connector 的当前原生模式。不要直接写 lvdrm_drm_rockchip.c 内部的 drm_buff;应通过 LVGL 对象更新画面,后端会完成 GEM 双缓冲和 DRM 提交。
3. 显示 RGB888 内存图像
当前验证 SDK 配置为 LV_COLOR_DEPTH=32。将 RGB888 数据转为 lv_color_t,再使用 lv_img 显示。像素数组和图像描述符必须在整个显示期间有效。
#define IMAGE_W 720
#define IMAGE_H 1280
static lv_color_t image_pixels[IMAGE_W * IMAGE_H];
static lv_img_dsc_t image_dsc = {
.header.always_zero = 0,
.header.w = IMAGE_W,
.header.h = IMAGE_H,
.header.cf = LV_IMG_CF_TRUE_COLOR,
.data_size = sizeof(image_pixels),
.data = (const uint8_t *)image_pixels,
};
static void rgb888_to_lvgl(const uint8_t *src, unsigned int src_stride)
{
unsigned int x, y;
for (y = 0; y < IMAGE_H; y++) {
for (x = 0; x < IMAGE_W; x++) {
const uint8_t *pixel = src + y * src_stride + x * 3;
image_pixels[y * IMAGE_W + x] =
LV_COLOR_MAKE(pixel[0], pixel[1], pixel[2]);
}
}
}
在 drm_disp_drv_init() 之后创建图像对象:
lv_obj_t *image = lv_img_create(lv_scr_act());
rgb888_to_lvgl(customer_rgb888, customer_stride);
lv_img_set_src(image, &image_dsc);
lv_obj_set_pos(image, 0, 0);
lv_obj_invalidate(image);
customer_rgb888 是输入帧数据地址,customer_stride 为其每行字节数。若源图像不是 RGB888,先按其格式转换;BGR888 需要交换 R/B,RGB565 和 YUV 不能直接套用上述循环。
4. 更新动态帧(推荐 LVGL 路径)
每获得完整新帧后,在同一个 LVGL/DRM 主线程执行:
rgb888_to_lvgl(customer_rgb888, customer_stride);
lv_obj_invalidate(image);
采集线程、网络线程或 DSMC 读取线程不能在 LVGL 渲染期间直接覆盖 image_pixels。推荐使用生产者/消费者双缓冲:生产者写后台帧,完整帧到达后通知主线程切换;主线程转换并调用 lv_obj_invalidate()。
对大多数 UI、状态画面和低至中等帧率图像,直接从 dsi_lvgl_colorbar.c 二次开发即可。lvdrm_drm_rockchip.c 已实现 GEM 双缓冲和 plane 提交,开发者只需处理输入帧格式与线程同步。
5. 使用 dsi_image_demo 开发高帧率原始图像
src/dsi_image_demo.c 是最小 DRM/KMS 示例,适合验证一张 RGB888 图像或做原始帧显示的起点。当前版本只申请一个 dumb buffer、设置一次 CRTC,然后 pause(),因此只能显示静态画面。
要用于相机、DSMC 或算法的动态输出,须将它改造为双缓冲 PageFlip 架构,不能在正在扫描的单缓冲上持续写入:
- 将单个
dumb、fb、pixels扩展为frame[2];每个 frame 分别创建 dumb buffer、Rockchip GEM 映射和 framebuffer。 - 仅在首帧使用
DRM_IOCTL_MODE_SETCRTC配置 connector、CRTC 和模式。 - 新图像总是写入后台 frame,按
pitch逐行填充 XRGB8888 像素;不要假设pitch == width * 4。 - 帧完整后,使用 DRM PageFlip 请求将后台 framebuffer 在 VSync 切换为前台,并等待 PageFlip 完成事件后再复用旧前台缓冲。
- 采集线程只写“空闲帧”;显示线程负责 PageFlip 和前后台交换。不要让两个线程同时写同一 framebuffer。
核心逻辑如下(伪代码,需按当前 libdrm 或项目封装实现 PageFlip 事件处理):
initial_modeset(frame[0].fb_id);
front = 0;
back = 1;
while (running) {
wait_until_source_frame_complete();
convert_source_to_xrgb8888(frame[back].pixels, frame[back].pitch);
page_flip_and_wait(crtc_id, frame[back].fb_id);
swap(front, back);
}
该路径适合追求较低 CPU 绘制开销的全屏原始图像;代价是开发者必须自行维护像素格式、双缓冲、VSync 事件和错误恢复。若只是显示 UI 或普通动态图像,优先使用前一节的 LVGL 路径。
运行 dsi_image_demo 前必须停止 dsi_lvgl_colorbar、rk_demo、Weston 或其他占用同一 CRTC/primary plane 的程序;测试结束后可重新启动 run_dsi_lvgl_colorbar.sh。
6. 接入 DSMC/FPGA 帧缓冲
现有 dsmc_demo 是 LocalBus 读写测试工具,不会显示图像。接入 DSMC 图像时,应新建或改造应用,使其:
- 打开并
mmap()/dev/dsmc/csX/regionY; - 根据 FPGA 协议找到帧起始偏移和帧完成标志;
- 在确认帧完整后,按实际格式/stride 从 DSMC 映射区复制并转换到
image_pixels; - 调用
lv_obj_invalidate(image)显示新帧。
在开始编码前,FPGA 必须提供帧缓冲偏移、宽高、格式、stride、双缓冲策略和帧完成通知方式。不要让 VOP 直接扫描 DSMC LocalBus 地址;先复制到 DRM GEM 显存是可移植且已验证的方案。
常见问题
| 现象 | 最可能层 | 处理动作 |
|---|---|---|
| 仅背光,无图像 | DTS/DSI 路由或面板初始化 | 检查 DSI、DPHY、VOP、route_dsi 和 dmesg 中 DCS 超时。 |
| 彩条不出现或与 GUI 交替 | DRM plane 被抢占 | 停止 rk_demo、Weston 或其他 DRM 应用后重试。 |
| 图像偏色 | 像素格式转换 | 核对 RGB/BGR 顺序、RGB565 字节序和 alpha。 |
| 图像错行或斜纹 | stride/分辨率 | 使用源帧实际 stride,逐行复制。 |
| 动态图像撕裂 | 帧缓冲并发访问 | 使用双缓冲和帧完成同步,不读写同一帧。 |
| 轻微整体亮度闪烁 | 背光/电源/面板链路 | 先用静态彩条排除软件刷新,再检查 PWM、供电和 DSI 信号。 |