指南 / TSENGCHEN BLOG

RK3506-MIPI-DSI-LVGL-DRM-Colorbar-README

05_Guid · 第 7 / 10 篇

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.cRockchip DRM 输出后端;负责 GEM 显存、双缓冲、plane 选择与提交。一般不需要修改。
src/dsmc_demo.cDSMC LocalBus 读写与带宽测试工具。(未通过测试)
src/dsi_image_demo.c早期 DSI 显示测试程序。
src/rockit_vo_demo.cRockit 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.mdDTS 中每项板级配置、安装与移植限制。
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_colorbar
  • scripts/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 架构,不能在正在扫描的单缓冲上持续写入:

  1. 将单个 dumb、fb、pixels 扩展为 frame[2];每个 frame 分别创建 dumb buffer、Rockchip GEM 映射和 framebuffer。
  2. 仅在首帧使用 DRM_IOCTL_MODE_SETCRTC 配置 connector、CRTC 和模式。
  3. 新图像总是写入后台 frame,按 pitch 逐行填充 XRGB8888 像素;不要假设 pitch == width * 4。
  4. 帧完整后,使用 DRM PageFlip 请求将后台 framebuffer 在 VSync 切换为前台,并等待 PageFlip 完成事件后再复用旧前台缓冲。
  5. 采集线程只写“空闲帧”;显示线程负责 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 图像时,应新建或改造应用,使其:

  1. 打开并 mmap() /dev/dsmc/csX/regionY;
  2. 根据 FPGA 协议找到帧起始偏移和帧完成标志;
  3. 在确认帧完整后,按实际格式/stride 从 DSMC 映射区复制并转换到 image_pixels;
  4. 调用 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 信号。
05_Guid · 文档目录
上一篇RK3506-DSMC-DSI-Master-Delivery下一篇RK3506G-EVB1-64MB-Feature-and-Trim