OpenHarmony 5.1.0 在 RK3568 上点屏全流程实战

1. 从零上手 OpenHarmony 5.1.0 在 RK3568 上的点屏全流程RK3568 这颗芯片在国产化嵌入式圈子里热度一直不低四核 A55、Mali-G52 GPU、双千兆网口、PCIe 3.0、SATA 3.0、USB 3.0 一应俱全最关键的是瑞芯微的文档和社区生态相对成熟拿来跑 OpenHarmony 做商显、工控、教育平板这类产品非常合适。但真正上手你会发现从源码拉取到屏幕点亮中间隔着编译工具链、内核配置、设备树适配、显示子系统调试好几道坎每一步都有坑。这篇内容就是把我自己在 RK3568 上跑 OpenHarmony 5.1.0 并成功点屏的完整过程整理出来包括源码编译环境的搭建、内核关键配置项的选择理由、设备树里显示相关节点的写法、以及点屏失败时怎么一步步排查。适合已经有嵌入式 Linux 基础、想快速在 RK3568 上把 OpenHarmony 跑起来并点亮屏幕的开发者参考也适合正在做 RK3568 产品化落地的团队做技术预研。OpenHarmony 5.1.0 这个版本在显示子系统上做了不少调整HDI 接口层和 DRM 框架的对接比早期版本规范了很多但这也意味着如果你拿的是老版本的适配代码直接往 5.1.0 上套会出问题。RK3568 的显示通路大致是GPU 渲染 → HDI 合成 → DRM 驱动 → VOP 控制器 → MIPI DSI/HDMI/eDP 接口 → 屏幕。点屏的本质就是让这条链路每一环都正常工作而设备树就是把这些硬件信息告诉内核的载体。下面我按实际操作的顺序从编译环境开始一步步拆开讲。1.1 为什么选择源码编译而不是直接用现成镜像很多人第一反应是去社区找个现成的 RK3568 OpenHarmony 镜像烧进去就完事了但实际做产品你会发现现成镜像的屏幕参数、分辨率、接口类型大概率跟你的硬件不匹配而且内核里一堆用不到的驱动会拖慢启动速度。源码编译的好处是你能完全控制内核配置和设备树针对自己的板子做裁剪。RK3568 的 SDK 通常包含 U-Boot、Kernel、Rootfs 三大部分OpenHarmony 5.1.0 的源码树里已经集成了瑞芯微的内核分支但默认配置是面向开发板的跟你的定制板子有差异。编译环境这块官方推荐 Ubuntu 20.04 或 22.04我实测 22.04 更稳主要是 Python 版本和依赖库的兼容性更好。内存建议 32GB 起步16GB 也能编但容易在链接阶段 OOM。磁盘至少留 200GB源码加上编译产物很容易超过 150GB。工具链方面OpenHarmony 5.1.0 用的是自带的 clang 工具链但内核编译还是走 GCC所以系统里要装好gcc-arm-linux-gnueabihf和aarch64-linux-gnu交叉编译工具。这里有个细节RK3568 是 64 位芯片内核编译用aarch64-linux-gnu-前缀但 U-Boot 的 TPL/SPL 阶段可能用到 32 位工具链两个都要装。注意不要用 Ubuntu 24.04我试过Python 3.12 跟 OpenHarmony 的构建脚本有兼容问题报错信息很隐晦排查起来浪费时间。1.2 源码拉取与目录结构速览OpenHarmony 5.1.0 的源码用 repo 工具管理拉取命令网上到处都是但关键是拉完之后你要知道代码在哪。RK3568 相关的代码主要分布在几个位置device/rockchip/rk3568下面是板级配置kernel/linux/linux-5.10是内核源码drivers/hdf_core/adapter/khdf/linux是 HDI 适配层foundation/graphic/graphic_2d是图形子系统。设备树文件在kernel/linux/linux-5.10/arch/arm64/boot/dts/rockchip/下面RK3568 的通用设备树是rk3568.dtsi板级设备树通常是rk3568-evb.dts或你自定义的rk3568-yourboard.dts。拉源码的时候有个技巧用repo init时加上--depth1可以只拉最新一次提交节省大量时间和磁盘空间。但如果你后续要查提交历史或者做 bisect就别加这个参数。另外repo sync的时候建议加-j8或更高取决于你的网络和 CPU 核心数我一般用-j16再高容易把磁盘 IO 打满反而变慢。2. 编译环境搭建与内核配置的关键决策编译环境搭建本身不复杂但有几个地方容易出错。首先是依赖包OpenHarmony 官方文档列了一长串apt install的命令但实际编译 RK3568 内核时还会缺一些库比如libssl-dev、bc、flex、bison、libelf-dev。这些在编译内核时如果缺失报错信息往往指向一个很奇怪的地方比如提示找不到某个头文件实际上是依赖没装全。我的做法是先把官方文档的依赖装完再额外补上这几个基本就不会再缺了。其次是 Python 环境OpenHarmony 的构建脚本依赖 Python 3.8 到 3.10Ubuntu 22.04 默认是 3.10没问题。但如果你系统里装了多个 Python 版本要确保python3指向正确的版本。可以用update-alternatives来管理或者直接在构建脚本里指定 Python 路径。我遇到过因为python3指向了 3.11 导致pycparser解析失败的情况报错信息是语法错误但实际上是版本不兼容。2.1 内核配置项的选择逻辑RK3568 的内核配置是点屏能否成功的关键。OpenHarmony 5.1.0 默认的rockchip_defconfig已经包含了很多驱动但显示相关的配置需要根据你的屏幕接口来调整。核心配置项包括CONFIG_DRM_ROCKCHIPy这是 RK3568 显示驱动的基础必须开。CONFIG_ROCKCHIP_DW_MIPI_DSIy如果你用 MIPI DSI 屏幕这个要开。CONFIG_ROCKCHIP_DW_HDMIyHDMI 输出需要。CONFIG_ROCKCHIP_ANALOGIX_DPyeDP 屏幕需要。CONFIG_DRM_PANEL_SIMPLEy通用面板驱动很多 MIPI 屏幕用这个就能点亮。CONFIG_BACKLIGHT_PWMy背光控制如果背光走 PWM 就必须开。CONFIG_PWM_ROCKCHIPyRK3568 的 PWM 控制器驱动。这些配置项在make menuconfig里都能找到但路径比较深建议直接用make ARCHarm64 rockchip_defconfig生成默认配置后再用scripts/config脚本或者直接编辑.config文件来修改。改完之后一定要跑make ARCHarm64 olddefconfig来补全依赖不然编译时会出现配置不一致的警告严重时直接编译失败。提示CONFIG_DRM_PANEL_SIMPLE这个驱动非常有用它支持通过设备树里的panel-simple节点来配置屏幕的时序参数不需要写额外的驱动代码。大部分标准 MIPI 屏幕都能用它点亮。2.2 设备树文件的组织方式RK3568 的设备树采用分层结构rk3568.dtsi是芯片级定义包含了所有外设控制器的基地址和默认配置。板级设备树通过#include rk3568.dtsi来引入然后覆盖或补充具体的引脚配置、时钟频率、屏幕参数。这种分层的好处是芯片级改动不影响板级板级改动也不会污染芯片级定义。显示相关的设备树节点主要涉及几个部分VOP 控制器节点、MIPI DSI 控制器节点、面板节点、背光节点、以及 GPIO 和 PWM 的引脚配置。VOP 是 Video Output ProcessorRK3568 有两个 VOPVOPB 支持 4K 输出VOPL 支持 1080P。点屏时要根据屏幕分辨率选择合适的 VOP如果屏幕是 1080P 或更低用 VOPL 就够了把 VOPB 留给其他显示设备或者不用。面板节点通常写成panel: panel { compatible simple-panel; ... }然后在 DSI 控制器节点里通过panel panel引用。背光节点类似backlight: backlight { compatible pwm-backlight; ... }在面板节点里通过backlight backlight关联。这种引用关系如果写错内核启动时不会报错但屏幕就是不亮排查起来很头疼。3. 显示子系统实操从设备树编写到屏幕点亮设备树编写是点屏的核心工作也是最容易出错的地方。我以一块常见的 10.1 寸 1920x1200 MIPI DSI 屏幕为例把关键节点的写法拆开讲。首先要在板级设备树的根节点下添加面板和背光节点然后在 DSI 控制器节点里引用它们最后配置 VOP 的输出路由和引脚。面板节点的关键属性包括compatible必须是simple-panel或者具体屏幕型号的兼容字符串power-supply指向一个 regulator 节点用于控制屏幕供电backlight指向背光节点port节点里定义endpoint通过remote-endpoint跟 DSI 控制器的endpoint对接。这个remote-endpoint的引用关系必须成对出现一边写错了链路就断了。背光节点的关键属性compatible pwm-backlightpwms pwm4 0 25000 0表示用 PWM4周期 25000 纳秒即 40kHz极性为 0brightness-levels定义亮度等级表通常写 0 到 255 的递增数组default-brightness-level指定默认亮度等级。PWM 频率的选择有讲究太低会有可听噪声太高背光 IC 可能响应不过来40kHz 到 100kHz 是比较安全的范围。3.1 MIPI DSI 控制器与 VOP 的对接DSI 控制器节点在rk3568.dtsi里已经有定义板级设备树里主要是覆盖status为okay然后补充panel引用和port配置。DSI 的port节点里通常有两个endpoint一个连面板一个连 VOP。连 VOP 的那个endpoint要指定remote-endpoint vopb_out_dsi或vopl_out_dsi取决于你用哪个 VOP。VOP 节点的配置相对简单主要是把对应的输出接口status设为okay然后在vopb或vopl节点里配置assigned-clocks和assigned-clock-rates来设定像素时钟。像素时钟的计算公式是像素时钟 水平总周期 × 垂直总周期 × 刷新率。以 1920x120060Hz 为例水平总周期通常比有效像素多出前后肩和同步头假设水平总周期 2100垂直总周期 1250那么像素时钟 2100 × 1250 × 60 ≈ 157.5MHz。这个值要跟屏幕规格书里的要求匹配偏差太大会导致画面抖动或花屏。注意像素时钟的计算一定要以屏幕规格书为准不同屏幕的前后肩参数差异很大。我见过有人直接抄开发板的参数结果屏幕能亮但画面偏移调了半天才发现是时序不对。3.2 引脚配置与电源域检查RK3568 的引脚复用非常灵活同一个物理引脚可以配置成 GPIO、PWM、MIPI DSI、I2C 等多种功能。设备树里的pinctrl节点就是用来指定引脚功能的。显示相关的引脚主要包括MIPI DSI 的差分数据线和时钟线、背光 PWM 引脚、屏幕复位 GPIO、电源使能 GPIO。这些引脚如果被其他功能占用或者 pinctrl 配置写错屏幕就不会亮。电源域检查是另一个容易被忽略的点。RK3568 有多个电源域MIPI DSI 的 IO 电压通常是 1.8V 或 1.2V如果设备树里配置的 regulator 电压跟实际硬件不匹配要么屏幕不亮要么长期工作不稳定。我建议在设备树里把每个 regulator 的regulator-min-microvolt和regulator-max-microvolt都写清楚不要依赖默认值。实操中我习惯先用万用表量一下屏幕连接器上的各路电压确认硬件供电正常再去调软件。如果电压都不对软件怎么调都没用。量电压的时候要注意有些屏幕的供电是受 GPIO 控制的需要先让系统启动到一定阶段GPIO 拉高之后才有电压。4. 点屏失败排查与常见问题速查点屏失败的表现有很多种屏幕完全不亮、背光亮但无画面、画面花屏、画面偏移、颜色异常。每种表现对应的排查方向不同。完全不亮先查供电和背光背光亮但无画面查 DSI 信号和 VOP 输出花屏查时序参数和时钟频率偏移查前后肩配置颜色异常查像素格式和 lane 映射。排查工具方面内核的dmesg是首选重点看 DRM 子系统的日志搜索rockchip-drm、dw-mipi-dsi、panel-simple这些关键字。如果 DSI 初始化失败日志里会有failed to attach panel或dsi phy init failed之类的提示。另外/sys/kernel/debug/dri/0/summary可以查看当前 DRM 的状态包括连接的显示设备、分辨率、刷新率等信息。如果这个文件里看不到你的面板说明设备树里的链路没建立起来。还有一个很实用的调试手段是测量 MIPI DSI 的时钟信号。用示波器或者逻辑分析仪接在 DSI 时钟差分线上如果有信号说明 DSI 控制器在工作没有信号就是控制器没初始化成功。这个手段能快速区分是控制器问题还是面板问题。不过 DSI 速率很高普通示波器可能测不准逻辑分析仪也要选支持高速差分信号的型号。4.1 常见问题速查表现象可能原因排查方法屏幕完全不亮供电缺失、背光未使能、DSI 未初始化量电压、查 dmesg、测 DSI 时钟背光亮但无画面DSI 链路未建立、VOP 未输出查/sys/kernel/debug/dri/0/summary画面花屏像素时钟偏差、lane 数不匹配核对屏幕规格书、调整时序参数画面偏移前后肩参数错误重新计算水平/垂直总周期颜色异常像素格式错误、lane 映射错误检查bus-format和>