1. 先说清楚为什么开发 OpenHarmony 一定要掌握硬件调试三板斧我这两年带着团队做开源鸿蒙 OpenHarmony 系统级开发从南向移植适配到北向应用联调踩过的硬件问题不计其数。很多刚入门的朋友经常问我一个问题系统起不来的时候我到底该从哪下手OpenHarmony 和安卓、Linux 这类系统最大的不同在于它是一个从内核到框架层再到应用层全部打通的分布式操作系统硬件适配的复杂度远高于普通 MCU 开发。你在开发板上跑一个标准系统往往要面对 Kernel、HDF硬件驱动框架、系统服务、应用框架之间的多层协作。任何一层出了问题表现出来的现象都是——板子起不来、外设不响应、系统卡死但你根本不知道问题出在哪。我自己的体会是OpenHarmony 开发调试最重要的不是写代码而是快速定位问题。而定位问题最快的方式永远是靠“三板斧”串口日志Shell Hilog、设备树Device Tree解析、以及内核日志dmesg。这三个手段配合起来能够覆盖 90% 以上的硬件调试场景。这篇文章不是泛泛而谈理论而是基于我在 RK3566、RK3568 这些主流开发板上做 OpenHarmony 系统适配时的真实经验把硬件调试的方法论和实操细节讲透。不管你是做南向移植、驱动开发还是做板级验证这套三板斧思路都适用。2. 第一板斧串口日志系统调试的“生命线”2.1 为什么串口是必须的而不是只靠屏幕或网络很多初学者拿到开发板第一反应是接上 HDMI 显示器、连上网络然后通过 SSH 或者 ADB 去操作系统。这样做不是不行但排查硬件问题时非常不方便——系统层面的崩溃、内核 panic、驱动加载失败往往发生得非常早这时候网络服务还没起来图形界面更是天方夜谭。串口则是一条独立的物理链路只要 CPU 和内存基本工作正常串口就能输出信息。哪怕内核崩溃了串口上的最后一行日志往往就是定位问题的关键线索。所以做 OpenHarmony 开发第一件事就是确认串口有没有接好、有没有输出。2.2 串口连接参数与接线细节OpenHarmony 标准系统的调试串口通常是 UART0 或者 UART2具体哪个口要看开发板原理图。以市面上常见的 RK3568 开发板为例调试串口经常复用排针上的 UART2三个引脚TX、RX、GND。接线时有一个经常被忽略的点交叉连接。板子的 TX 要接 USB 转串口工具的 RX板子的 RX 接工具的 TX地线必须共地。接反了不会烧硬件但串口完全没输出新手容易在这里卡很久。串口参数这块OpenHarmony 标准系统一般固定为参数项值波特率15000001.5Mbps数据位8停止位1校验位None流控无这里有个特别容易踩的坑OpenHarmony 标准系统的串口波特率并不是常见的 115200而是1500000。如果用默认的 115200 去连串口会输出乱码或者干脆没有反应。我用 MobaXterm、PuTTY 和 minicom 都试过只要波特率选对基本都能稳定输出。Windows 下建议用 MobaXtermLinux 下可以直接 minicom 或者 picocom。2.3 串口输出里到底有什么信息串口一旦通了你会看到系统启动时的完整日志流。相比之后要讲的 dmesg串口日志是全链路实时的从 bootloaderU-Boot到 kernel 再到 init 进程全程都能看到。正常启动时串口的输出顺序大概是这样的U-Boot 阶段打印 DDR 初始化信息、设备树加载情况、boot 分区选择。Kernel 阶段打印内核版本、内核命令行参数、设备树解析过程、各驱动 probe 是否成功。Init 阶段启动第一个用户态进程进而拉起 OHOS 的各种系统服务。如果某个驱动加载失败串口上通常会看到类似这样的信息[ 1.234567] rockchip-i2c0 fddc0000.i2c: fail to get clock [ 1.240123] rockchip-i2c0 fddc0000.i2c: probe failed, err -22这两行日志其实是极其重要的提示I2C0 控制器在解析设备树时拿不到时钟信息probe 直接失败。看到这种输出你就能立刻锁定问题方向——去查设备树里的 clock 属性而不是盲目改驱动代码。2.4 无输出时的排查思路插上串口发现完全没有动静这时候别慌。按我之前排障的经验按以下顺序排查90% 能解决确认 USB 转串口工具在电脑上识别成功。Windows 下看设备管理器里的 COM 口号Linux 下用ls /dev/ttyUSB*。确认波特率是 1500000不是 115200。确认接线是交叉连接且 GND 接好了。拨动开发板上的启动拨码开关确认是否已经切换到对应的启动介质比如从 SD 卡启动还是从 eMMC 启动。按开发板上的复位键或者重新上电观察是否有输出。如果以上都正常但仍然无输出很大概率是板子上的 bootloader 没烧录或者烧录有问题。这时候就要回到烧录工具去重新烧写 U-Boot 镜像。3. 第二板斧设备树Device Tree搞懂板级配置的关键3.1 OpenHarmony 里设备树到底是什么角色熟悉 Linux 开发的朋友对设备树一定不陌生。OpenHarmony 的南向体系虽然有自己的 HDF 驱动框架但内核仍然基于 Linux 内核演变而来设备树依然承担着“描述硬件”的核心职责。说人话设备树就是一块开发板的“配置单”上面写清楚了这块板子上有哪些外设、每个外设连接在哪个控制器上、用哪个引脚、时钟频率是多少、中断号是几。系统启动时内核解析这段配置单并据此为每个外设挂载对应的驱动。为什么设备树调试在 OpenHarmony 开发中如此重要因为 OpenHarmony 的设备树并不是一个简单孤立的 dts 文件它往往要经过多级引入涉及 SoC 级 dtsi、板级 dts、以及多个 overlay 文件的叠加。你一旦改错一个属性系统很可能在启动早期就挂掉。3.2 RK3568 设备树的开源代码结构网上经常有人问RK3568 的 OpenHarmony 设备树文件太多不知道该看哪一个。这确实是新手最容易困惑的地方。以 OpenHarmony 标准系统的 kernel 源码为例RK3568 相关设备树通常放在kernel/linux/linux-5.10/arch/arm64/boot/dts/rockchip/目录下你会看到大量文件比如rk3568-evb.dtsEVB 评估板的主设备树rk3568-evb1-ddr4-v10.dts针对不同内存型号的变体rk356x.dtsiRK3566/RK3568 共用的 SoC 级描述rk3568-evb.dtsi板级外设描述很多人看到这么多文件直接懵圈其实核心思路很简单从最终编译入口往上追溯。先找到你板子对应的主 dts 文件看它 include 了哪些 dtsi逐层展开就能理清楚。比如你想给一块 RK3568 的板子增加一个 I2C 接口的触摸屏。修改的时候要明确I2C 控制器本身比如 I2C3在 SoC 级 dtsi 里已经定义好了你只需要在板级 dtsi 里补充这个 I2C 总线下挂的具体设备节点即可。不需要去动 SoC 级的定义。3.3 怎么判断当前系统用的是哪个设备树这句话是我最常被问到的也是调试时必须先确定的问题我手上的系统到底加载了哪一份设备树OpenHarmony 标准系统起来后有几个办法可以确认。最简单的是在串口日志的 kernel 阶段查看。正常启动时内核会打印类似这样的信息Kernel command line: rootPARTUUID... rw rootwait consolettyFIQ0,1500000但这只是内核命令行并不直接告诉你设备树文件是哪个。更准确的方法是在内核日志里搜Model或者machine相关的关键词。如果你在串口里看到了 Kernel 打印的板名比如Machine model: Rockchip RK3568 EVB1 DDR4 V10 Board这一般是设备树里model属性字段的值。如果你不确定还可以在系统起来之后通过 debugfs 导出实际的设备树二进制dtb到用户态再用dtc工具反编译成 dts 来查看。具体命令是mkdir /tmp/dtb cp /sys/firmware/fdt /tmp/dtb/fdt.dtb dtc -I dtb -O dts -o /tmp/dtb/fdt.dts /tmp/dtb/fdt.dtb如果系统里没有 dtc 工具也可以把fdt.dtb拷贝到电脑上用 Ubuntu 下的 device-tree-compiler 包去反编译。这一步能让你彻底看清当前生效的设备树长什么样对于排查“为什么我的节点不生效”这类问题特别有效。3.4 设备树调试的常见隐患设备树写对了系统不一定能起来设备树写错了系统一定起不来或者功能异常。结合我的经验以下几个坑最常见属性值与硬件不符。I2C 速率、GPIO 编号、中断触发方式这些参数必须在物理层面和硬件原理图对得上。比如触摸屏的 reset 脚你在 dts 里写的 GPIO 编号和原理图不一致驱动就会初始化失败。引脚复用冲突。RK 平台大量使用 pinmux引脚复用机制。同一个物理引脚可能既能当 GPIO 也能当 I2C 数据线或者 UART 信号线。如果两处配置冲突动态日志往往不直接报错只会导致某个外设随机性失灵。这是最耗时的排障类型。设备树 overlay 优先级。OpenHarmony 标准系统在 u-boot 阶段支持设备树 overlay 叠加。你修改的 dts 最终生成的 dtb要经过 bootloader 覆盖确保真正加载的是你编译出来的那份 dtb。否则会出现“改了没生效”的问题。4. 第三板斧内核日志与用户态日志工具组合4.1 dmesg 与 hilog 的分工串口能看实时日志但很多日志刷得很快加上打印时序不同静态分析困难。这时候需要用到系统的日志收集机制。OpenHarmony 系统里日志分两大块内核日志dmesg和用户态日志hilog。dmesg用来查看内核环形缓冲区里的历史消息适合排查驱动加载、设备树解析、硬件资源申请等问题。hilogOpenHarmony 用户态的统一日志系统各系统服务和应用层都通过 hilog 对外输出日志。这两者分工明确内核阶段和驱动问题主要靠 dmesg上层服务和 App 问题主要靠 hilog。4.2 内核日志的实用排查方法系统起来之后在串口终端登录执行dmesg | grep -i fail\|error这是最直接的排查方式。把内核日志里所有报错信息过滤出来往往一眼就能看到问题所在。这里分享一个我自己总结的排查驱动加载问题的四步法用dmesg看有没有驱动 probe 失败的打印确认是被哪个子系统拒绝的。dmesg中没有明显报错时查看对应总线上是否有设备注册成功。筛选设备树相关日志确认节点是否被正确解析。如果上述都正常基本可以怀疑驱动内部行为需要进一步看驱动自己的 debug 日志。这几步看着简单但能帮你避免漫无目的地翻代码。4.3 hilog 的常用命令与过滤技巧在 OpenHarmony 系统里hilog 工具的使用频率非常高。以下是高频命令hilog # 实时查看日志 hilog -z tag # 按标签过滤 hilog -l level # 按日志级别过滤如 ERROR、WARN hilog -f /data/log/hilog.log # 输出到文件比如你怀疑某个硬件服务启动失败可以这样过滤hilog | grep -i hdf\|driver\|i2c结合 HDF 驱动框架中HDF_LOG_TAG打点基本能快速把用户态驱动报错定位到具体模块。4.4 一个案例推理外设不工作的调试思路单纯讲日志命令有点干。我拿一个实际项目举例。我们当时调试一块 RK3566 的板子外接的 AP6xxx WiFi 模组扫描不到信号。按照三板斧思路我是这么定位的第一步串口全实时日志里看到 WiFi 驱动加载的打印但没有报错说明驱动模块本身 probe 成功了。第二步dmesg | grep -i wifi查看内核日志里 WiFi 相关的完整链路。结果发现sdio总线上没有识别到设备也就是说 WiFi 芯片和 CPU 之间根本没有完成 SDIO 握手。第三步回到设备树检查 SDIO 节点的引脚复用配置。对比原理图发现 SDIO 的数据线在 dts 中被复用成了别的功能索性修改后重新编译 dtb再烧录验证。整个过程三板斧各用一次逻辑清晰问题半小时内就定位到了。如果一开始就闷头读驱动代码很可能陷入泥潭。5. 联合实战从“系统起不来”到“外设跑不通”的排查链路5.1 场景 A上电后串口无任何输出这种场景往往是环境或 bootloader 层面的问题。排查思路按部就班来确认供电正常。很多开发板上电后指示灯亮但电流不足会导致 CPU 无法正常启动。确认 boot 介质和烧录内容。通过拨码开关确认启动介质重新烧录 U-Boot。确认串口工具本身没问题。用短接 TX/RX 的方式做回环测试看有没有自发的输出。如果 U-Boot 能启动但内核没有输出可以进入 U-Boot 命令行手动确认 boot 参数是否正确。5.2 场景 B内核频繁重启串口出现 panic串口日志里如果看到Kernel panic - not syncing往往是 vfs 无法挂载根文件系统或者内核访问非法内存。此时优先排查内核命令行里root指定的分区是否正确initramfs 或 vendor_boot 分区是否烧录正确设备树里内存节点是否与实际内存大小匹配这种情况我遇到过很多次原因往往不是代码而只是镜像没烧对、分区表对不上。5.3 场景 C系统正常启动但某个外设不可用这一块在前面 WiFi 调试的例子里已经完整走了一遍。再补充一个非常常见的情况外设在dmesg里没有任何相关日志像完全不存在一样。这就基本可以断定是设备树没有编译进该外设节点或者是 HDF 驱动没有被系统加载。优先检查设备树节点是否存在再看驱动的module_init是否有触发条件。5.4 实战中的日志分析技巧总结把这三个场景走下来你会发现一个共同规律任何硬件问题的排查都可以拆成三层确认。排查层使用的工具解决的问题物理层与 Bootloader串口、U-Boot 指令硬件是否启动、镜像是否烧对内核与驱动层dmesg、设备树驱动加载情况、引脚配置是否合理用户态服务层hilog上层服务是否正常调用驱动能力每层都有独立的日志源和判断标准。按照这层递进式的排查逻辑来硬件问题基本不会成为拦路虎。6. 三板斧之外的补充手段HiTrace 与调试内核选项6.1 为什么还需要补充手段三板斧解决的是定位问题但有些问题比较隐蔽例如性能类、时序类、资源竞争类问题单靠日志很难发现。比如外设响应偶尔超时、I2C 传输偶发失败这类问题出现频率不高靠人眼盯日志几乎不可能抓住。6.2 HiTrace分布式性能追踪利器OpenHarmony 提供了 HiTrace 分布式跟踪机制。它让你能够追踪一次硬件调用从应用层到内核驱动的全链路耗时。在代码里可以通过HitraceAPI 方便地打点在命令行工具里可以这样抓取hitrace --trace_begin app # 执行你的测试操作 hitrace --trace_dump hitrace --trace_finish对于判定“外设响应慢是驱动问题还是上层调度问题”非常有用。你能看到一次调用各环节的时间消耗从而定位瓶颈是内核态还是用户态。6.3 调试内核选项与编译开关如果你的目标是驱动开发强烈建议在编译内核的时候打开 debugging 相关选项。在kernel/linux/linux-5.10/arch/arm64/configs/rockchip_linux_defconfig中增加以下配置CONFIG_DEBUG_KERNELy CONFIG_DEBUG_INFOy CONFIG_DYNAMIC_DEBUGy CONFIG_DEVTMPFSy动态调试打开后驱动里的dev_dbg打印才能真正输出。如果你的驱动使用了dev_info都还没输出那就要检查日志级别设置。内核日志级别可以通过内核命令行参数或者/proc/sys/kernel/printk调整echo 8 4 1 7 /proc/sys/kernel/printk串口上会立刻出现更多调试信息。7. 你必须知道的几个隐藏知识点7.1 关于拨码开关和分区表RK3568 系列开发板通常支持从 eMMC、SD 卡、SPI Flash 多种介质启动。拨码开关的组合方式在原理图里都有说明。但很多人遇到的问题是烧录成功了重启后却还是旧系统运行。这种情况很大概率是启动介质没有切到烧录介质上或者 bootloader 里的 boot 命令固定从某个分区启动。7.2 关于内核命令行内核命令行中的console参数决定了调试串口用哪个设备。RK 平台常用consolettyFIQ0,1500000其中 ttyFIQ0 是 Rockchip 的 FIQ 调试串口机制。如果你更改了调试串口的引脚这个参数也要对应修改否则串口输出会消失或者出现在错误的物理接口上。7.3 关于无法打印用户态日志时的应急方案有时候系统起不来用户态日志根本看不到。这时候很多新手就慌了。其实可以退回到内核阶段用一个最简根文件系统比如仅仅是一个 busybox initramfs来启动系统先确认内核和驱动是好的再逐步叠加 OpenHarmony 的用户态组件。这个方法虽然原始但在做底层适配时是完全必要的降级调试手段。8. 按我的经验先建立日志习惯再谈系统开发做 OpenHarmony 硬件调试时间越久我越觉得真正的核心能力其实不在于解决某一个问题而在于建立一套固定的调试心智模型。串口、设备树、内核日志这三板斧其实就是这套模型的具体投射。最开始我带团队时成员遇到问题第一反应是去翻代码翻很久没找到头绪再回来看日志。正确的方式应该是反过来先花几分钟把日志完整的看一遍确认问题边界再精准跳进代码。通过大量实战对比我观测到后者平均能把调试时间压缩到前者的三分之一以下。针对刚入门的读者我建议先把今天的三个工具分别在开发板上跑一遍把正常启动的日志完整保留一份。后续再遇到问题拿异常状态和正常日志做对比这比什么都管用。串口日志、设备树这些本质上就是在和硬件对话。听得懂它在说什么问题就已经解决了一大半。
OpenHarmony硬件调试三板斧：串口、设备树与内核日志实战指南
1. 先说清楚为什么开发 OpenHarmony 一定要掌握硬件调试三板斧我这两年带着团队做开源鸿蒙 OpenHarmony 系统级开发从南向移植适配到北向应用联调踩过的硬件问题不计其数。很多刚入门的朋友经常问我一个问题系统起不来的时候我到底该从哪下手OpenHarmony 和安卓、Linux 这类系统最大的不同在于它是一个从内核到框架层再到应用层全部打通的分布式操作系统硬件适配的复杂度远高于普通 MCU 开发。你在开发板上跑一个标准系统往往要面对 Kernel、HDF硬件驱动框架、系统服务、应用框架之间的多层协作。任何一层出了问题表现出来的现象都是——板子起不来、外设不响应、系统卡死但你根本不知道问题出在哪。我自己的体会是OpenHarmony 开发调试最重要的不是写代码而是快速定位问题。而定位问题最快的方式永远是靠“三板斧”串口日志Shell Hilog、设备树Device Tree解析、以及内核日志dmesg。这三个手段配合起来能够覆盖 90% 以上的硬件调试场景。这篇文章不是泛泛而谈理论而是基于我在 RK3566、RK3568 这些主流开发板上做 OpenHarmony 系统适配时的真实经验把硬件调试的方法论和实操细节讲透。不管你是做南向移植、驱动开发还是做板级验证这套三板斧思路都适用。2. 第一板斧串口日志系统调试的“生命线”2.1 为什么串口是必须的而不是只靠屏幕或网络很多初学者拿到开发板第一反应是接上 HDMI 显示器、连上网络然后通过 SSH 或者 ADB 去操作系统。这样做不是不行但排查硬件问题时非常不方便——系统层面的崩溃、内核 panic、驱动加载失败往往发生得非常早这时候网络服务还没起来图形界面更是天方夜谭。串口则是一条独立的物理链路只要 CPU 和内存基本工作正常串口就能输出信息。哪怕内核崩溃了串口上的最后一行日志往往就是定位问题的关键线索。所以做 OpenHarmony 开发第一件事就是确认串口有没有接好、有没有输出。2.2 串口连接参数与接线细节OpenHarmony 标准系统的调试串口通常是 UART0 或者 UART2具体哪个口要看开发板原理图。以市面上常见的 RK3568 开发板为例调试串口经常复用排针上的 UART2三个引脚TX、RX、GND。接线时有一个经常被忽略的点交叉连接。板子的 TX 要接 USB 转串口工具的 RX板子的 RX 接工具的 TX地线必须共地。接反了不会烧硬件但串口完全没输出新手容易在这里卡很久。串口参数这块OpenHarmony 标准系统一般固定为参数项值波特率15000001.5Mbps数据位8停止位1校验位None流控无这里有个特别容易踩的坑OpenHarmony 标准系统的串口波特率并不是常见的 115200而是1500000。如果用默认的 115200 去连串口会输出乱码或者干脆没有反应。我用 MobaXterm、PuTTY 和 minicom 都试过只要波特率选对基本都能稳定输出。Windows 下建议用 MobaXtermLinux 下可以直接 minicom 或者 picocom。2.3 串口输出里到底有什么信息串口一旦通了你会看到系统启动时的完整日志流。相比之后要讲的 dmesg串口日志是全链路实时的从 bootloaderU-Boot到 kernel 再到 init 进程全程都能看到。正常启动时串口的输出顺序大概是这样的U-Boot 阶段打印 DDR 初始化信息、设备树加载情况、boot 分区选择。Kernel 阶段打印内核版本、内核命令行参数、设备树解析过程、各驱动 probe 是否成功。Init 阶段启动第一个用户态进程进而拉起 OHOS 的各种系统服务。如果某个驱动加载失败串口上通常会看到类似这样的信息[ 1.234567] rockchip-i2c0 fddc0000.i2c: fail to get clock [ 1.240123] rockchip-i2c0 fddc0000.i2c: probe failed, err -22这两行日志其实是极其重要的提示I2C0 控制器在解析设备树时拿不到时钟信息probe 直接失败。看到这种输出你就能立刻锁定问题方向——去查设备树里的 clock 属性而不是盲目改驱动代码。2.4 无输出时的排查思路插上串口发现完全没有动静这时候别慌。按我之前排障的经验按以下顺序排查90% 能解决确认 USB 转串口工具在电脑上识别成功。Windows 下看设备管理器里的 COM 口号Linux 下用ls /dev/ttyUSB*。确认波特率是 1500000不是 115200。确认接线是交叉连接且 GND 接好了。拨动开发板上的启动拨码开关确认是否已经切换到对应的启动介质比如从 SD 卡启动还是从 eMMC 启动。按开发板上的复位键或者重新上电观察是否有输出。如果以上都正常但仍然无输出很大概率是板子上的 bootloader 没烧录或者烧录有问题。这时候就要回到烧录工具去重新烧写 U-Boot 镜像。3. 第二板斧设备树Device Tree搞懂板级配置的关键3.1 OpenHarmony 里设备树到底是什么角色熟悉 Linux 开发的朋友对设备树一定不陌生。OpenHarmony 的南向体系虽然有自己的 HDF 驱动框架但内核仍然基于 Linux 内核演变而来设备树依然承担着“描述硬件”的核心职责。说人话设备树就是一块开发板的“配置单”上面写清楚了这块板子上有哪些外设、每个外设连接在哪个控制器上、用哪个引脚、时钟频率是多少、中断号是几。系统启动时内核解析这段配置单并据此为每个外设挂载对应的驱动。为什么设备树调试在 OpenHarmony 开发中如此重要因为 OpenHarmony 的设备树并不是一个简单孤立的 dts 文件它往往要经过多级引入涉及 SoC 级 dtsi、板级 dts、以及多个 overlay 文件的叠加。你一旦改错一个属性系统很可能在启动早期就挂掉。3.2 RK3568 设备树的开源代码结构网上经常有人问RK3568 的 OpenHarmony 设备树文件太多不知道该看哪一个。这确实是新手最容易困惑的地方。以 OpenHarmony 标准系统的 kernel 源码为例RK3568 相关设备树通常放在kernel/linux/linux-5.10/arch/arm64/boot/dts/rockchip/目录下你会看到大量文件比如rk3568-evb.dtsEVB 评估板的主设备树rk3568-evb1-ddr4-v10.dts针对不同内存型号的变体rk356x.dtsiRK3566/RK3568 共用的 SoC 级描述rk3568-evb.dtsi板级外设描述很多人看到这么多文件直接懵圈其实核心思路很简单从最终编译入口往上追溯。先找到你板子对应的主 dts 文件看它 include 了哪些 dtsi逐层展开就能理清楚。比如你想给一块 RK3568 的板子增加一个 I2C 接口的触摸屏。修改的时候要明确I2C 控制器本身比如 I2C3在 SoC 级 dtsi 里已经定义好了你只需要在板级 dtsi 里补充这个 I2C 总线下挂的具体设备节点即可。不需要去动 SoC 级的定义。3.3 怎么判断当前系统用的是哪个设备树这句话是我最常被问到的也是调试时必须先确定的问题我手上的系统到底加载了哪一份设备树OpenHarmony 标准系统起来后有几个办法可以确认。最简单的是在串口日志的 kernel 阶段查看。正常启动时内核会打印类似这样的信息Kernel command line: rootPARTUUID... rw rootwait consolettyFIQ0,1500000但这只是内核命令行并不直接告诉你设备树文件是哪个。更准确的方法是在内核日志里搜Model或者machine相关的关键词。如果你在串口里看到了 Kernel 打印的板名比如Machine model: Rockchip RK3568 EVB1 DDR4 V10 Board这一般是设备树里model属性字段的值。如果你不确定还可以在系统起来之后通过 debugfs 导出实际的设备树二进制dtb到用户态再用dtc工具反编译成 dts 来查看。具体命令是mkdir /tmp/dtb cp /sys/firmware/fdt /tmp/dtb/fdt.dtb dtc -I dtb -O dts -o /tmp/dtb/fdt.dts /tmp/dtb/fdt.dtb如果系统里没有 dtc 工具也可以把fdt.dtb拷贝到电脑上用 Ubuntu 下的 device-tree-compiler 包去反编译。这一步能让你彻底看清当前生效的设备树长什么样对于排查“为什么我的节点不生效”这类问题特别有效。3.4 设备树调试的常见隐患设备树写对了系统不一定能起来设备树写错了系统一定起不来或者功能异常。结合我的经验以下几个坑最常见属性值与硬件不符。I2C 速率、GPIO 编号、中断触发方式这些参数必须在物理层面和硬件原理图对得上。比如触摸屏的 reset 脚你在 dts 里写的 GPIO 编号和原理图不一致驱动就会初始化失败。引脚复用冲突。RK 平台大量使用 pinmux引脚复用机制。同一个物理引脚可能既能当 GPIO 也能当 I2C 数据线或者 UART 信号线。如果两处配置冲突动态日志往往不直接报错只会导致某个外设随机性失灵。这是最耗时的排障类型。设备树 overlay 优先级。OpenHarmony 标准系统在 u-boot 阶段支持设备树 overlay 叠加。你修改的 dts 最终生成的 dtb要经过 bootloader 覆盖确保真正加载的是你编译出来的那份 dtb。否则会出现“改了没生效”的问题。4. 第三板斧内核日志与用户态日志工具组合4.1 dmesg 与 hilog 的分工串口能看实时日志但很多日志刷得很快加上打印时序不同静态分析困难。这时候需要用到系统的日志收集机制。OpenHarmony 系统里日志分两大块内核日志dmesg和用户态日志hilog。dmesg用来查看内核环形缓冲区里的历史消息适合排查驱动加载、设备树解析、硬件资源申请等问题。hilogOpenHarmony 用户态的统一日志系统各系统服务和应用层都通过 hilog 对外输出日志。这两者分工明确内核阶段和驱动问题主要靠 dmesg上层服务和 App 问题主要靠 hilog。4.2 内核日志的实用排查方法系统起来之后在串口终端登录执行dmesg | grep -i fail\|error这是最直接的排查方式。把内核日志里所有报错信息过滤出来往往一眼就能看到问题所在。这里分享一个我自己总结的排查驱动加载问题的四步法用dmesg看有没有驱动 probe 失败的打印确认是被哪个子系统拒绝的。dmesg中没有明显报错时查看对应总线上是否有设备注册成功。筛选设备树相关日志确认节点是否被正确解析。如果上述都正常基本可以怀疑驱动内部行为需要进一步看驱动自己的 debug 日志。这几步看着简单但能帮你避免漫无目的地翻代码。4.3 hilog 的常用命令与过滤技巧在 OpenHarmony 系统里hilog 工具的使用频率非常高。以下是高频命令hilog # 实时查看日志 hilog -z tag # 按标签过滤 hilog -l level # 按日志级别过滤如 ERROR、WARN hilog -f /data/log/hilog.log # 输出到文件比如你怀疑某个硬件服务启动失败可以这样过滤hilog | grep -i hdf\|driver\|i2c结合 HDF 驱动框架中HDF_LOG_TAG打点基本能快速把用户态驱动报错定位到具体模块。4.4 一个案例推理外设不工作的调试思路单纯讲日志命令有点干。我拿一个实际项目举例。我们当时调试一块 RK3566 的板子外接的 AP6xxx WiFi 模组扫描不到信号。按照三板斧思路我是这么定位的第一步串口全实时日志里看到 WiFi 驱动加载的打印但没有报错说明驱动模块本身 probe 成功了。第二步dmesg | grep -i wifi查看内核日志里 WiFi 相关的完整链路。结果发现sdio总线上没有识别到设备也就是说 WiFi 芯片和 CPU 之间根本没有完成 SDIO 握手。第三步回到设备树检查 SDIO 节点的引脚复用配置。对比原理图发现 SDIO 的数据线在 dts 中被复用成了别的功能索性修改后重新编译 dtb再烧录验证。整个过程三板斧各用一次逻辑清晰问题半小时内就定位到了。如果一开始就闷头读驱动代码很可能陷入泥潭。5. 联合实战从“系统起不来”到“外设跑不通”的排查链路5.1 场景 A上电后串口无任何输出这种场景往往是环境或 bootloader 层面的问题。排查思路按部就班来确认供电正常。很多开发板上电后指示灯亮但电流不足会导致 CPU 无法正常启动。确认 boot 介质和烧录内容。通过拨码开关确认启动介质重新烧录 U-Boot。确认串口工具本身没问题。用短接 TX/RX 的方式做回环测试看有没有自发的输出。如果 U-Boot 能启动但内核没有输出可以进入 U-Boot 命令行手动确认 boot 参数是否正确。5.2 场景 B内核频繁重启串口出现 panic串口日志里如果看到Kernel panic - not syncing往往是 vfs 无法挂载根文件系统或者内核访问非法内存。此时优先排查内核命令行里root指定的分区是否正确initramfs 或 vendor_boot 分区是否烧录正确设备树里内存节点是否与实际内存大小匹配这种情况我遇到过很多次原因往往不是代码而只是镜像没烧对、分区表对不上。5.3 场景 C系统正常启动但某个外设不可用这一块在前面 WiFi 调试的例子里已经完整走了一遍。再补充一个非常常见的情况外设在dmesg里没有任何相关日志像完全不存在一样。这就基本可以断定是设备树没有编译进该外设节点或者是 HDF 驱动没有被系统加载。优先检查设备树节点是否存在再看驱动的module_init是否有触发条件。5.4 实战中的日志分析技巧总结把这三个场景走下来你会发现一个共同规律任何硬件问题的排查都可以拆成三层确认。排查层使用的工具解决的问题物理层与 Bootloader串口、U-Boot 指令硬件是否启动、镜像是否烧对内核与驱动层dmesg、设备树驱动加载情况、引脚配置是否合理用户态服务层hilog上层服务是否正常调用驱动能力每层都有独立的日志源和判断标准。按照这层递进式的排查逻辑来硬件问题基本不会成为拦路虎。6. 三板斧之外的补充手段HiTrace 与调试内核选项6.1 为什么还需要补充手段三板斧解决的是定位问题但有些问题比较隐蔽例如性能类、时序类、资源竞争类问题单靠日志很难发现。比如外设响应偶尔超时、I2C 传输偶发失败这类问题出现频率不高靠人眼盯日志几乎不可能抓住。6.2 HiTrace分布式性能追踪利器OpenHarmony 提供了 HiTrace 分布式跟踪机制。它让你能够追踪一次硬件调用从应用层到内核驱动的全链路耗时。在代码里可以通过HitraceAPI 方便地打点在命令行工具里可以这样抓取hitrace --trace_begin app # 执行你的测试操作 hitrace --trace_dump hitrace --trace_finish对于判定“外设响应慢是驱动问题还是上层调度问题”非常有用。你能看到一次调用各环节的时间消耗从而定位瓶颈是内核态还是用户态。6.3 调试内核选项与编译开关如果你的目标是驱动开发强烈建议在编译内核的时候打开 debugging 相关选项。在kernel/linux/linux-5.10/arch/arm64/configs/rockchip_linux_defconfig中增加以下配置CONFIG_DEBUG_KERNELy CONFIG_DEBUG_INFOy CONFIG_DYNAMIC_DEBUGy CONFIG_DEVTMPFSy动态调试打开后驱动里的dev_dbg打印才能真正输出。如果你的驱动使用了dev_info都还没输出那就要检查日志级别设置。内核日志级别可以通过内核命令行参数或者/proc/sys/kernel/printk调整echo 8 4 1 7 /proc/sys/kernel/printk串口上会立刻出现更多调试信息。7. 你必须知道的几个隐藏知识点7.1 关于拨码开关和分区表RK3568 系列开发板通常支持从 eMMC、SD 卡、SPI Flash 多种介质启动。拨码开关的组合方式在原理图里都有说明。但很多人遇到的问题是烧录成功了重启后却还是旧系统运行。这种情况很大概率是启动介质没有切到烧录介质上或者 bootloader 里的 boot 命令固定从某个分区启动。7.2 关于内核命令行内核命令行中的console参数决定了调试串口用哪个设备。RK 平台常用consolettyFIQ0,1500000其中 ttyFIQ0 是 Rockchip 的 FIQ 调试串口机制。如果你更改了调试串口的引脚这个参数也要对应修改否则串口输出会消失或者出现在错误的物理接口上。7.3 关于无法打印用户态日志时的应急方案有时候系统起不来用户态日志根本看不到。这时候很多新手就慌了。其实可以退回到内核阶段用一个最简根文件系统比如仅仅是一个 busybox initramfs来启动系统先确认内核和驱动是好的再逐步叠加 OpenHarmony 的用户态组件。这个方法虽然原始但在做底层适配时是完全必要的降级调试手段。8. 按我的经验先建立日志习惯再谈系统开发做 OpenHarmony 硬件调试时间越久我越觉得真正的核心能力其实不在于解决某一个问题而在于建立一套固定的调试心智模型。串口、设备树、内核日志这三板斧其实就是这套模型的具体投射。最开始我带团队时成员遇到问题第一反应是去翻代码翻很久没找到头绪再回来看日志。正确的方式应该是反过来先花几分钟把日志完整的看一遍确认问题边界再精准跳进代码。通过大量实战对比我观测到后者平均能把调试时间压缩到前者的三分之一以下。针对刚入门的读者我建议先把今天的三个工具分别在开发板上跑一遍把正常启动的日志完整保留一份。后续再遇到问题拿异常状态和正常日志做对比这比什么都管用。串口日志、设备树这些本质上就是在和硬件对话。听得懂它在说什么问题就已经解决了一大半。
