1. 拿到RK3568这块板子之后先想清楚点屏这件事到底难在哪很多人第一次在OpenHarmony上折腾RK3568点屏心态都是这样的源码拉下来编译一把过烧进去屏幕就该亮了。结果往往是——串口有打印HDMI没信号MIPI屏背光都不亮或者亮了但花屏、偏移、颜色不对。然后就开始漫无目的地搜rk3568 点屏翻到一堆碎片化的帖子改一个参数编译半小时烧录五分钟看结果三秒钟一天下来屏幕还是黑的。我前后在RK3568上点过MIPI DSI屏、RGB屏、LVDS转接屏也踩过触摸方向不对、背光时序不匹配、设备树节点被覆盖这些坑。这篇文章不讲空泛的概念就按我实际操作的顺序把从源码编译到内核配置调优这条链路完整走一遍。适合已经拿到RK3568开发板、准备在OpenHarmony 5.1.0上点亮一块屏的开发者也适合之前点过Android或纯Linux、但第一次接触OpenHarmony显示子系统的朋友。先说清楚一个认知点屏从来不是改一个参数的事它是编译系统 内核配置 设备树 显示驱动 背光 触摸这一整条链路的协同结果。任何一环不对屏幕都不会给你好脸色。所以下面我会按这条链路的顺序展开每一环都告诉你为什么这么做、怎么验证、错了会怎样。2. OpenHarmony 5.1.0 源码编译别急着make先把环境对齐2.1 编译环境的选择与依赖安装OpenHarmony 5.1.0的编译对Ubuntu版本有要求我实测下来Ubuntu 20.04和22.04都能跑通但22.04上某些Python依赖需要额外处理。建议直接用20.04省心。内存至少16GB低于这个数编译到图形子系统那一步大概率OOM我见过8GB机器编译到一半被kill的报错信息还特别隐晦让人以为是代码问题。依赖安装这一步官方文档给的包列表是基础但实际编译RK3568的图形栈时还会缺一些。我习惯一次性把下面这些装齐sudo apt-get update sudo apt-get install -y git-lfs build-essential gcc g make sudo apt-get install -y libssl-dev libncurses5-dev libncursesw5-dev sudo apt-get install -y python3 python3-pip python3-venv sudo apt-get install -y genext2fs mtools dosfstools sudo apt-get install -y device-tree-compiler sudo apt-get install -y liblz4-tool其中device-tree-compiler也就是dtc特别关键后面设备树的编译和反编译全靠它。很多人编译报错dtc not found就是漏了这个。Python环境我强烈建议用虚拟环境隔离不要污染系统Python。OpenHarmony的编译脚本对Python版本敏感系统里如果混了多个版本会出现明明装了模块却import失败的诡异现象。python3 -m venv ~/ohos-env source ~/ohos-env/bin/activate pip3 install --upgrade pip pip3 install pycryptodome提示每次开新终端编译前记得先source ~/ohos-env/bin/activate否则编译脚本会去找系统Python报错信息往往指向一个和Python毫无关系的模块排查起来很浪费时间。2.2 拉取源码与RK3568产品配置源码用repo工具管理先装repo再初始化。这里有个细节OpenHarmony 5.1.0的分支名要选对用错分支会导致RK3568的板级配置目录根本不存在。mkdir ~/ohos cd ~/ohos 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这一步耗时很长网络不稳的话建议加-j4控制并发别贪多。同步完之后进入device/board/目录看看有没有rk3568相关的板级目录这是判断源码是否完整的第一道关卡。编译命令针对RK3568通常是这样./build.sh --product-name rk3568 --ccache--ccache强烈建议加上第一次编译可能40分钟到1小时之后增量编译能压到几分钟。没有ccache的话你每改一次设备树都要等一次完整编译心态会崩。2.3 编译产物里到底哪个文件才是你要烧的编译完成后产物在out/rk3568/packages/phone/images/目录下。这里要认清几个关键镜像镜像文件作用点屏相关度boot.img内核设备树极高设备树改动主要在这里system.img系统分区中显示框架配置可能涉及vendor.img厂商分区中HDF显示驱动配置userdata.img用户数据低uboot.img引导程序中开机logo和显示初始化点屏调试阶段改得最多的就是boot.img因为设备树dtb被打包在里面。每次改完设备树重新编译后只需要烧boot.img就能验证不用全量烧录这个技巧能帮你省下大量时间。3. 内核配置显示相关的开关一个都不能少3.1 为什么默认配置点不亮屏OpenHarmony给RK3568的默认内核配置defconfig是一个能跑起来的最小集合它保证了系统启动但显示相关的驱动模块很多是没开的。这就解释了为什么很多人烧完默认镜像串口一切正常屏幕却毫无反应——内核里压根没加载对应的显示驱动。RK3568的显示子系统涉及几个关键部分VOPVideo Output Processor视频输出处理器、MIPI DSI控制器、背光PWM控制器、以及具体的屏panel驱动。这些在menuconfig里分散在不同菜单下需要逐个确认。进入内核配置cd kernel/linux/linux-5.10 make ARCHarm64 rockchip_defconfig make ARCHarm64 menuconfig3.2 必须确认打开的关键配置项下面这些配置项是我点屏时逐个核对过的缺一个都可能导致屏幕不亮或者亮得不正常CONFIG_DRMy CONFIG_DRM_ROCKCHIPy CONFIG_ROCKCHIP_DW_MIPI_DSIy CONFIG_DRM_PANELy CONFIG_BACKLIGHT_CLASS_DEVICEy CONFIG_BACKLIGHT_PWMy CONFIG_PWM_ROCKCHIPy CONFIG_DRM_PANEL_SIMPLEy CONFIG_PHY_ROCKCHIP_INNO_VIDEO_COMBO_PHYy其中CONFIG_DRM_PANEL_SIMPLE是通用panel驱动如果你用的屏没有专门的驱动靠它配合设备树里的panel描述就能点亮。CONFIG_PHY_ROCKCHIP_INNO_VIDEO_COMBO_PHY是MIPI DPHY的驱动MIPI屏没它直接黑屏。注意改完menuconfig后不要直接make savedefconfig覆盖原defconfig除非你确定要永久修改。调试阶段建议保留.config验证通过后再决定是否固化到defconfig。3.3 内核配置的验证方法配置改完编译出boot.img后怎么确认驱动真的加载了最直接的办法是看启动日志dmesg | grep -i -E drm|vop|dsi|panel|backlight如果看到类似rockchip-drm display-subsystem: bound、panel-simple相关的probe成功信息说明驱动加载正常。如果只有VOP绑定成功但没有panel那问题就在设备树里panel节点没配对。我遇到过一次dmesg里显示failed to find panel查了半天发现是设备树里panel节点的compatible字符串和驱动里注册的不一致。这种问题日志里其实写得很清楚关键是要养成看dmesg的习惯而不是盯着黑屏瞎猜。4. 设备树配置点屏的核心战场4.1 设备树在RK3568显示链路里的角色设备树Device Tree本质上是把硬件长什么样这件事从内核代码里剥离出来用一份描述文件告诉内核这块板子上接了哪个屏、用哪路MIPI、背光接在哪个PWM、复位脚是哪个GPIO。内核启动时解析这份描述去匹配对应的驱动。RK3568的设备树文件在kernel/linux/linux-5.10/arch/arm64/boot/dts/rockchip/目录下和RK3568相关的主要是rk3568.dtsiSoC级公共描述和具体的板级dts文件比如rk3568-evb1-ddr4-v10.dts之类。改的时候要改板级dts不要动dtsidtsi是所有RK3568板子共用的改了会影响其他配置。4.2 MIPI DSI屏的设备树节点怎么写一块MIPI屏要工作设备树里至少要描述清楚四件事DSI控制器、panel本身、背光、供电和复位。下面是一个我实际用过的结构以一块常见的MIPI屏为例dsi0 { status okay; rockchip,lane-rate 1000; panel: 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 68000000; hactive 800; vactive 1280; hback-porch 40; hfront-porch 40; hsync-len 10; vback-porch 20; vfront-porch 20; vsync-len 4; }; }; }; };这里每一个参数都不是随便填的。clock-frequency是像素时钟由分辨率、刷新率和消隐区共同决定填错了要么花屏要么刷新率不对。dsi,lanes要和屏的物理排线一致4 lane的屏写成2 lane直接黑屏。dsi,format要和屏的接口定义匹配RGB888和RGB565搞混颜色会明显失真。4.3 背光节点屏幕亮了但很暗八成是这里背光是最容易被忽略的一环。屏幕能显示内容但亮度极低或者完全不亮问题往往出在背光节点。RK3568的背光通常走PWMbacklight: backlight { compatible pwm-backlight; pwms pwm4 0 25000 0; brightness-levels 0 20 20 21 21 22 22 23 23 24 24 25 25 26 26 27 /* 中间省略实际要写满256级 */ 255 ; default-brightness-level 200; enable-gpios gpio3 RK_PC2 GPIO_ACTIVE_HIGH; };pwms里的25000是PWM周期单位纳秒对应40kHz这是大多数背光IC能接受的频率。频率太低会有可听噪声太高有些背光IC响应不过来。brightness-levels是一张亮度映射表OpenHarmony的背光框架会按这个表来调光如果表里全是0那屏幕就是黑的。我踩过一个坑enable-gpios的极性写反了结果背光一直是关的但dmesg里没有任何报错因为从内核角度看PWM输出是正常的只是使能脚电平不对。这种问题只能靠万用表量电压或者示波器看波形来定位。4.4 触摸屏方向不对怎么改触摸方向不对是RK3568点屏的高频问题尤其是竖屏改横屏的场景。触摸芯片比如GT9xx、FT5x06通过I2C接入方向由设备树里的touchscreen-inverted-x、touchscreen-inverted-y、touchscreen-swapped-x-y这几个属性控制i2c3 { status okay; gt9xx: gt9xx5d { compatible goodix,gt9xx; reg 0x5d; touch-gpio gpio0 RK_PB5 IRQ_TYPE_LEVEL_LOW; reset-gpio gpio0 RK_PB6 GPIO_ACTIVE_HIGH; touchscreen-inverted-x; touchscreen-swapped-x-y; }; };竖屏改横屏通常需要同时调整swapped-x-y和其中一个inverted。具体怎么组合取决于屏的物理安装方向没有万能公式得试。我的经验是先只加swapped-x-y看效果如果方向对了但上下反了再加inverted-y如果左右反了加inverted-x。每次只改一个属性改完单独编译boot.img验证这样能快速定位到正确的组合。5. 从编译到烧录再到验证的完整闭环5.1 单独编译设备树和内核的高效方法全量编译一次要几十分钟但调试设备树时完全没必要全量编。改完dts后可以只编内核./build.sh --product-name rk3568 --build-target kernel --ccache这样只重新编译内核和设备树几分钟就能出新的boot.img。更进一步如果只是想验证设备树语法可以单独用dtc编译dtc -I dts -O dtb -o test.dtb rk3568-your-board.dts这一步能快速发现语法错误比如括号不匹配、属性名拼错不用等整个内核编译完才报错。5.2 烧录工具与分区选择RK3568烧录一般用瑞芯微的烧录工具进入loader模式后连接。调试阶段我建议只烧boot.img因为设备树和内核都在里面。烧录前确认板子确实进了loader模式否则工具会提示找不到设备。烧录完成后串口工具波特率1500000这是RK3568的默认调试串口波特率不是常见的115200很多人卡在这里以为串口坏了看启动日志。重点看几个时间点uboot阶段有没有识别到显示设备、内核阶段drm和panel有没有probe成功、系统起来后显示服务有没有正常启动。5.3 分层排查屏幕不亮时按这个顺序查屏幕不亮的原因可能分布在链路的任何一层盲目乱改效率极低。我总结的排查顺序是这样的排查层级检查内容判断依据硬件层排线、供电、背光电压万用表量电压示波器看信号uboot层开机logo是否显示有logo说明基础显示通路OK内核层dmesg里drm/panel/vop日志probe成功与否设备树层节点status、compatible、时序参数与屏规格书逐项核对框架层OpenHarmony显示服务日志系统起来后屏幕有无内容按这个顺序从下往上查能快速缩小范围。比如uboot阶段就有logo说明VOP和基本的显示通路没问题问题大概率在panel驱动或设备树时序上如果uboot阶段就没logo那要往更底层查可能是uboot的显示配置或者硬件本身的问题。6. 几个让我印象深刻的坑和对应的解法6.1 设备树节点被覆盖导致配置不生效有一次我明明在板级dts里把panel节点配好了编译烧录后却完全没效果。查了很久才发现板级dts里include了一个公共的dtsi那个dtsi里也定义了同名节点而且顺序在后把我的配置覆盖了。设备树的节点合并规则是后出现的属性覆盖先出现的同名节点会合并而不是替换。解法是确认include顺序或者用/delete-node/先删掉再重新定义。这个坑的隐蔽性在于编译不报错日志也不报错就是配置不生效非常折磨人。6.2 时序参数差一点就花屏MIPI屏的时序参数前后消隐、同步宽度必须严格按屏规格书来。我有一次把hback-porch少写了一个0屏幕能亮但右侧有一条竖条纹看起来像是屏坏了。实际上就是消隐区不够数据没对齐。这种问题改回正确参数立刻就好但如果不熟悉时序原理很容易误判成硬件故障。6.3 背光PWM频率引起的闪烁背光用低频PWM驱动时肉眼可能看不出闪烁但拍照或者录像时会出现明显的横纹。我遇到过PWM频率设成1kHz的情况屏幕看着正常但用手机拍就有条纹。把频率提到20kHz以上就消失了。所以背光PWM频率建议不低于20kHz既避开可听噪声也避开可见闪烁。6.4 触摸和显示不同步偶尔会遇到显示正常但触摸坐标完全错乱的情况尤其是换了屏但没同步更新触摸配置的时候。触摸的坐标系是独立的显示旋转了不代表触摸也跟着转。解决办法就是在触摸节点里正确配置swapped-x-y和inverted属性让触摸坐标系和显示坐标系对齐。这个必须实测没有捷径。7. 调优阶段值得花时间做的几件事屏幕点亮只是第一步点亮之后还有调优空间。第一件事是确认刷新率是否达标用modetest或者系统自带的显示信息接口看实际刷新率如果和屏规格书差太多回头检查clock-frequency和消隐参数。第二件事是背光曲线默认的线性映射在低亮度区往往偏亮可以自定义brightness-levels做成非线性曲线低亮度更细腻。第三件事是开机logo到系统界面的过渡如果uboot显示了logo但系统起来后黑一下再亮说明显示通路上有重新初始化的动作可以通过调整uboot和内核的显示配置减少这段黑屏时间。RK3568这块芯片的显示能力其实挺强多路VOP、MIPI、LVDS、RGB都支持点屏过程中积累的设备树配置经验换一块屏或者换一个分辨率大部分是可以复用的。真正需要重新调的往往就是panel节点里的时序参数和触摸方向这几项。把这条链路走通一次之后后面再点新屏速度会快很多。最后分享一个我自己的习惯每点通一块屏就把对应的设备树片段、内核配置差异、以及踩过的坑记成一个独立的patch文件存起来。下次遇到类似型号的屏直接参考patch改比翻聊天记录和搜索历史靠谱得多。设备树这东西配置对了就是对了配置错了报错信息又往往不直接所以把验证过的配置沉淀下来是长期做点屏这件事最省力的方式。