1. 为什么选择 RK3568 跑 OpenHarmony 5.1.0RK3568 这颗芯片在国产化嵌入式圈子里热度一直没降过。四核 Cortex-A55、主频 2.0GHz、内置 Mali-G52 GPU、支持双屏异显、原生三路显示输出再加上瑞芯微对主线内核和 U-Boot 的持续投入让它成了不少团队从 STM32MP1、i.MX6ULL 往上升级时的首选。OpenHarmony 5.1.0 是当前 LTS 版本里比较成熟的一个分支ArkUI 框架、分布式软总线、HDF 驱动框架都已经稳定拿它来配 RK3568 做点屏属于芯片选型不踩坑、系统版本不折腾的组合。但真到动手的时候问题就来了。官方文档给的是通用流程具体到 RK3568 这块板子从源码拉取、编译配置、内核设备树修改到屏幕点亮中间有一堆细节是文档里不会写的。比如屏幕时序参数怎么算、VOP 端口怎么分配、背光 PWM 通道怎么选、MIPI DSI 和 LVDS 的初始化顺序有什么讲究这些都得靠实际调试积累。这篇内容就是把我自己在 RK3568 上跑 OpenHarmony 5.1.0 点屏的完整过程整理出来。从源码编译环境搭建开始到内核设备树配置、屏幕参数调试、常见问题排查每一步都给出可复现的操作和参数计算过程。适合已经有一定嵌入式 Linux 基础、想快速在 RK3568 上把 OpenHarmony 跑起来并点亮屏幕的开发者。如果你之前只玩过单片机或者没接触过设备树建议先把 Linux 设备树的基本概念过一遍再来看会顺畅很多。2. 编译环境搭建与源码拉取2.1 硬件与系统环境准备编译 OpenHarmony 对机器要求不低。我实测下来Ubuntu 20.04 LTS 是最稳的22.04 也能跑但个别依赖包版本会有冲突。机器配置建议至少 16GB 内存、8 核 CPU、500GB 可用磁盘空间。源码拉取加上编译中间产物轻松超过 200GB磁盘不够会在编译到一半的时候报错非常浪费时间。具体环境清单如下项目推荐配置说明操作系统Ubuntu 20.04 LTS官方验证最充分的版本内存16GB 以上低于 16GB 编译容易 OOMCPU8 核以上影响编译速度不影响结果磁盘500GB SSD源码编译产物镜像Python3.8.x不要用 3.10脚本兼容性有问题Node.js14.x 或 16.x编译 ArkUI 相关组件需要依赖包安装这一步官方给的命令基本够用但我建议额外装几个工具后面调试会用上sudo apt-get update sudo apt-get install -y binutils git git-lfs gnupg flex bison gperf \ build-essential zip curl zlib1g-dev gcc-multilib g-multilib \ libc6-dev-i386 lib32ncurses5-dev x11proto-core-dev libx11-dev \ lib32z1-dev ccache libgl1-mesa-dev libxml2-utils xsltproc unzip \ m4 bc screen genext2fs device-tree-compiler make libffi-dev \ libssl-dev mtools dosfstools注意git-lfs 一定要装OpenHarmony 源码里有大文件是通过 LFS 管理的不装的话拉取会报错或者文件不完整。Python 版本这块要特别小心。Ubuntu 20.04 默认是 Python 3.8没问题。如果你手动升级过系统 Python建议用 update-alternatives 切回 3.8或者用 virtualenv 隔离一个 3.8 环境专门用来编译。2.2 源码拉取与版本切换OpenHarmony 5.1.0 的源码通过 repo 工具管理。先装 repomkdir ~/bin curl https://gitee.com/oschina/repo/raw/fork_flow/repo-py3 -o ~/bin/repo chmod ax ~/bin/repo pip3 install -i https://repo.huaweicloud.com/repository/pypi/simple requests然后把 ~/bin 加到 PATH 里接着初始化仓库mkdir ~/openharmony cd ~/openharmony repo init -u https://gitee.com/openharmony/manifest.git -b OpenHarmony-5.1.0-Release --no-repo-verify repo sync -c repo forall -c git lfs pullrepo sync 这一步耗时比较长取决于网络情况我这边大概跑了 40 分钟。如果中途断了直接重新执行 repo sync -c 会断点续传不用从头来。拉完之后切到 RK3568 的板级配置。OpenHarmony 5.1.0 里 RK3568 的适配代码在 device/rockchip 目录下产品名是 rk3568。确认一下ls device/rockchip/rk3568/能看到 config.json、BUILD.gn 这些文件就说明板级支持已经拉下来了。2.3 编译配置与首次全量编译编译前先执行环境脚本./build/prebuilts_download.sh这个脚本会下载编译工具链大概 5GB 左右。下载完之后开始配置编译目标./build.sh --product-name rk3568 --ccacheccache 强烈建议开启第一次全量编译大概 1.5 到 2 小时开了 ccache 之后增量编译能快很多。如果机器内存只有 16GB建议加个 -j8 限制并行任务数不然容易在链接阶段 OOM。编译成功后镜像输出在 out/rk3568/packages/phone/images/ 目录下主要用到这几个文件boot.img内核和 ramdisksystem.img系统分区vendor.img厂商分区userdata.img用户数据分区MiniLoaderAll.bin一级引导parameter.txt分区表烧录用瑞芯微的 RKDevToolWindows 下操作比较方便。板子进 loader 模式按住 recovery 键上电工具识别到设备后加载分区表把对应镜像填进去烧就行。实操心得第一次烧录建议把 userdata.img 也烧上不然系统起来后可能因为分区格式不对导致挂载失败。另外 parameter.txt 里的分区大小要根据实际 eMMC 容量调整我用的板子是 8GB eMMC默认配置够用。3. 内核设备树配置与屏幕点亮3.1 RK3568 显示子系统架构理解要点屏先得搞清楚 RK3568 的显示通路是怎么走的。RK3568 内部有个 VOPVideo Output Processor模块支持三个显示端口VP0、VP1、VP2。每个 VP 可以独立配置分辨率、时序、输出接口。输出接口这边支持 MIPI DSI、LVDS、RGB、HDMI、eDP 几种。典型的点屏链路是这样的VOP → 显示接口控制器MIPI DSI / LVDS / RGB→ 屏幕设备树里要配的就是这条链路上的每一环。VOP 这边要配端口分配、时钟、电源域接口控制器要配通道数、时钟频率、数据格式屏幕这边要配时序参数、背光、复位引脚。OpenHarmony 5.1.0 用的是 Linux 5.10 内核显示框架走的是 DRMDirect Rendering Manager。设备树里的显示节点要符合 DRM 框架的绑定规范跟早期 FBDEV 时代的写法差别挺大这点要注意。3.2 屏幕时序参数计算屏幕时序是点屏最核心的参数算错了屏幕要么不亮要么花屏要么显示偏移。以一块常见的 7 寸 MIPI 屏为例规格书给的参数通常是这样的分辨率1024x600像素时钟51.2MHzHSD水平同步宽度20HBP水平后沿160HFP水平前沿160VSD垂直同步宽度3VBP垂直后沿12VFP垂直前沿12这些参数直接填到设备树的 display-timings 节点里就行。但有些屏幕规格书给的是总周期而不是分项参数这时候要自己算水平总周期 HSD HBP 有效像素 HFP 垂直总周期 VSD VBP 有效行数 VFP像素时钟 水平总周期 × 垂直总周期 × 刷新率比如上面那块屏水平总周期 20 160 1024 160 1364垂直总周期 3 12 600 12 627刷新率 60Hz 的话像素时钟 1364 × 627 × 60 ≈ 51.3MHz跟规格书给的 51.2MHz 基本吻合。注意像素时钟允许有 1% 到 2% 的偏差屏幕一般都能正常显示。但如果偏差超过 5%可能会出现闪烁或者不同步。3.3 设备树修改实操RK3568 的板级设备树在 kernel/arch/arm64/boot/dts/rockchip/ 目录下。找到你板子对应的 dts 文件比如 rk3568-evb1-ddr4-v10.dtsi显示相关的配置通常在这个文件或者它 include 的 dtsi 里。先配 VOP 端口分配。假设我们用 MIPI DSI 接口屏幕接在 VP0 上vop { status okay; assigned-clocks cru DCLK_VOP0, cru DCLK_VOP1, cru DCLK_VOP2; assigned-clock-parents pmucru PLL_HPLL, cru PLL_VPLL, cru PLL_GPLL; }; vop_mmu { status okay; };然后是 MIPI DSI 控制器dsi0 { status okay; rockchip,lane-rate 1000; panel0 { compatible simple-panel-dsi; reg 0; backlight backlight; reset-gpios gpio3 RK_PC0 GPIO_ACTIVE_LOW; enable-gpios gpio3 RK_PC1 GPIO_ACTIVE_HIGH; dsi,flags (MIPI_DSI_MODE_VIDEO | MIPI_DSI_MODE_VIDEO_BURST); dsi,format MIPI_DSI_FMT_RGB888; dsi,lanes 4; display-timings { native-mode timing0; timing0: timing0 { clock-frequency 51200000; hactive 1024; vactive 600; hback-porch 160; hfront-porch 160; hsync-len 20; vback-porch 12; vfront-porch 12; vsync-len 3; hsync-active 0; vsync-active 0; de-active 1; pixelclk-active 0; }; }; }; };背光配置backlight: backlight { compatible pwm-backlight; pwms pwm4 0 25000 0; brightness-levels 0 4 8 16 32 64 128 255; default-brightness-level 6; enable-gpios gpio3 RK_PC2 GPIO_ACTIVE_HIGH; };这里 pwm4 是背光用的 PWM 通道25000 是周期单位纳秒对应 40kHz最后的 0 表示极性。brightness-levels 是亮度等级映射表default-brightness-level 是默认亮度索引。3.4 编译内核与验证设备树改完之后单独编译内核验证./build.sh --product-name rk3568 --build-target kernel编译产物在 out/rk3568/kernel/ 目录下把 boot.img 烧进去重启。系统起来后通过串口或者 adb 连上去检查显示是否正常cat /sys/class/drm/card0-DSI-1/status如果返回 connected说明屏幕被识别到了。再看分辨率cat /sys/class/drm/card0-DSI-1/modes应该输出 1024x600。如果 status 是 disconnected说明设备树配置有问题重点检查 reset-gpios 和 enable-gpios 的引脚定义是否正确。实操心得RK3568 的 GPIO 编号计算方式是 bank × 32 group × 8 index。比如 GPIO3_C0 就是 3×32 2×8 0 112。设备树里写 RK_PC0 这种宏定义编译时会自动转换但排查问题的时候心里要清楚实际编号是多少。4. 常见问题排查与调优技巧4.1 屏幕不亮的分层排查法屏幕不亮是最常见的问题排查要按层次来从电源到信号逐级确认。第一层背光。背光不亮的话屏幕看起来是黑的但实际可能已经有显示了只是看不见。用万用表量背光使能引脚看有没有拉高。如果使能正常但背光还是不亮检查 PWM 输出cat /sys/class/pwm/pwmchip4/pwm0/duty_cycle正常应该是个非零值。如果是 0说明背光驱动没起来检查设备树里 backlight 节点的 status 是不是 okay。第二层复位和使能时序。MIPI 屏对复位时序有要求一般是复位拉低至少 10ms然后拉高再等 120ms 才能发初始化命令。RK3568 的 panel 驱动里有个 prepare 回调时序就是在这里控制的。如果屏幕规格书要求的时序跟驱动默认的不一样要在设备树里加 delay 参数panel0 { ... reset-delay-ms 10; init-delay-ms 120; enable-delay-ms 50; };第三层MIPI 信号。如果背光和时序都没问题屏幕还是不亮就要查 MIPI 信号了。最直接的方法是量 MIPI 时钟差分对的频率正常应该是 lane-rate 的一半。比如 lane-rate 配的 1000Mbps时钟应该是 500MHz。量不到信号的话检查 DSI 控制器的 status 和时钟配置。第四层VOP 端口。如果 MIPI 有信号但屏幕显示异常可能是 VOP 端口分配错了。RK3568 的 VP0 和 VP1 支持的输出接口不一样VP0 支持 DSI 和 LVDSVP1 支持 HDMI 和 RGB。接 DSI 屏必须用 VP0。4.2 显示花屏与偏移问题花屏通常是时序参数不对。重点检查这几个参数现象可能原因排查方法整体花屏像素时钟偏差过大重新计算 clock-frequency水平方向偏移HBP 或 HFP 不对对照规格书核对垂直方向滚动VSD 或 VBP 不对检查 vsync-len颜色异常数据格式不匹配确认 dsi,format 是 RGB888局部闪烁lane-rate 过高降低到 800Mbps 试试我遇到过一次花屏查了半天发现是 hsync-active 和 vsync-active 的极性配反了。规格书里写的是低电平有效设备树里配成了 1高有效改成 0 就正常了。这种细节规格书里不一定写得很清楚实在拿不准就两种极性都试一下。4.3 触摸屏方向调整点屏之后经常遇到触摸方向不对的问题尤其是竖屏改横屏的时候。RK3568 的触摸驱动走的是 I2C 接口设备树里配触摸控制器i2c3 { status okay; gt9xx: gt9xx5d { compatible goodix,gt9xx; reg 0x5d; interrupt-parent gpio3; interrupts RK_PA5 IRQ_TYPE_LEVEL_LOW; reset-gpios gpio3 RK_PA4 GPIO_ACTIVE_LOW; touchscreen-size-x 1024; touchscreen-size-y 600; touchscreen-inverted-x; touchscreen-swapped-x-y; }; };方向调整靠这几个属性touchscreen-inverted-xX 轴反转touchscreen-inverted-yY 轴反转touchscreen-swapped-x-yX 和 Y 轴交换竖屏改横屏一般是加 touchscreen-swapped-x-y如果方向还是反的再配合 inverted 属性调整。这四个属性组合起来有八种情况实际调试的时候一个个试找到正确的组合就行。注意触摸方向调整只影响触摸坐标不影响显示。显示方向要在 panel 节点里通过 rotation 属性调整两者要配合着改。4.4 性能调优与稳定性验证屏幕点亮之后还要做一些性能调优和稳定性验证。首先是 VOP 时钟调优。RK3568 的 VOP 时钟源可以选择 HPLL、VPLL、GPLL不同时钟源的抖动特性不一样。实测下来VPLL 在 51.2MHz 附近的抖动最小显示最稳定。设备树里通过 assigned-clock-parents 指定assigned-clock-parents pmucru PLL_HPLL, cru PLL_VPLL, cru PLL_GPLL;其次是内存带宽调优。高分辨率屏幕对内存带宽要求比较高如果系统跑起来之后发现显示有撕裂或者卡顿可以在 dts 里提高 VOP 的 QoS 优先级vop { ... rockchip,grf grf; rockchip,pmu pmu; };稳定性验证方面我一般会跑这几个测试连续显示 24 小时看有没有花屏或者闪屏反复开关背光 1000 次验证背光驱动稳定性触摸画线测试检查有没有断点或者跳点高低温测试如果有条件-20°C 到 70°C 各跑 2 小时这几个测试跑下来没问题基本就可以交付了。5. 从点屏到产品化的几个关键决策5.1 屏幕选型与供应链考量点屏成功只是第一步产品化的时候屏幕选型要考虑更多因素。MIPI 屏虽然带宽高、线少但供应链稳定性不如 LVDS 和 RGB 屏。如果产品生命周期比较长建议优先选 LVDS 或者 RGB 接口的屏幕驱动简单替代品也多。RK3568 支持双屏异显如果产品需要两个屏幕VP0 接主屏MIPI 或 LVDSVP1 接副屏RGB 或 HDMI。两个屏幕的分辨率和刷新率可以独立配置但要注意总带宽不能超过 VOP 的处理能力。实测 VP0 跑 1024x60060Hz 加 VP1 跑 1280x72060Hz 是没问题的再高就要降刷新率了。5.2 内核裁剪与启动优化产品化的时候内核裁剪能明显缩短启动时间。OpenHarmony 5.1.0 默认内核配置比较全很多驱动用不上。裁剪的时候重点保留这几块DRM 显示框架和 RK3568 VOP 驱动MIPI DSI / LVDS / RGB 接口驱动触摸驱动GT9xx、FT5x06 等常用型号背光 PWM 驱动裁剪完之后内核大小能从 20MB 降到 12MB 左右启动时间缩短 1 到 2 秒。裁剪方法是在 kernel/arch/arm64/configs/ 目录下找到 rk3568_defconfig用 make menuconfig 调整配置保存后重新编译。5.3 设备树版本管理设备树文件是跟硬件强相关的不同批次的板子可能引脚定义不一样。建议把设备树文件纳入版本管理每个硬件版本对应一个 dts 文件命名规则比如 rk3568-product-v1.dts、rk3568-product-v2.dts。编译的时候通过参数指定用哪个./build.sh --product-name rk3568 --build-target kernel --dts rk3568-product-v2这样硬件改版的时候软件这边只需要切换 dts 文件不用改代码维护起来清晰很多。5.4 调试工具链准备最后分享几个我常用的调试工具能省不少时间rkdeveloptool瑞芯微官方的烧录工具命令行版本适合自动化脚本dtschema设备树语法检查工具改完 dts 先跑一遍能提前发现语法错误drm_info查看 DRM 设备状态和显示参数比直接读 sysfs 方便i2c-tools调试触摸和屏幕初始化的时候用 i2cdetect 确认 I2C 地址这些工具在 Ubuntu 上都能直接 apt 安装装好之后调试效率能提升不少。我在实际项目里踩过的最大一个坑是设备树里 GPIO 引脚定义跟硬件原理图对不上。原理图上写的是 GPIO3_C0设备树里写成了 GPIO3_B0差了一个 group结果屏幕死活不亮。后来养成了一个习惯改完设备树先对着原理图把每个引脚编号重新算一遍确认无误再编译。这个习惯帮我省了很多返工时间。