故障排除

文档版本：V1.0 | 适用系统：RT-Thread | 适用硬件：C-3576BQ V10 核心板 + M4-R2（ShimetaPi）底板 | 更新日期：2026-10-23

1. 概述

本文档汇总 M4-R2（RK3576）平台上 RT-Thread 系统开发过程中遇到的常见问题与故障排除方法，涵盖启动失败、串口通信异常、外设驱动问题、内存问题、AMP 多核协同问题及构建编译问题。

前置条件：熟悉 RT-Thread 基础框架与 RK3576 平台（可参考RT-Thread环境与工程入口与BSP与启动）。故障现象与解决方法的验证状态以实际 RK3576 SDK 为准。

2. 故障定位流程

2.1 通用排查步骤

  1. 确认硬件连接：调试串口（1500000bps）、电源（5V 典型）、复位按钮
  2. 确认串口输出：是否有启动日志，日志停在哪个阶段
  3. 确认镜像加载：RT-Thread 镜像是否被 U-Boot 正确加载
  4. 确认板级初始化：时钟、引脚、内存配置是否正确
  5. 逐层排查：按 启动 → 内核 → 设备 → 应用 顺序逐层排查

2.2 启动日志阶段判断

日志特征故障阶段排查方向
无任何输出硬件/烧录/电源检查电源、串口接线、镜像
U-Boot 有输出但跳转后无输出镜像跳转/入口地址检查镜像入口点与加载地址
RT-Thread 版权信息后停止板级初始化阶段检查 rt_hw_board_init()
内核启动但无 msh 提示符控制台/finsh 配置检查 finsh 与串口配置
进入 msh 后应用崩溃应用代码阶段检查应用线程与内存

3. 常见问题与处理方法

3.1 启动失败问题

现象已确认原因处理方法状态
串口无任何输出串口波特率错误确认串口终端波特率设置为 1500000已验证
串口无任何输出调试串口接线错误检查 TX→RXD、RX→TXD、GND 接线（3.3V 电平）已验证
串口无任何输出镜像未加载检查 U-Boot 中镜像加载地址与入口点是否匹配待板上验证
启动后立即复位内存配置错误检查链接脚本内存布局与 DTS reserved-memory 是否一致待板上验证
启动停在版权信息板级初始化卡死检查 rt_hw_board_init() 中时钟/引脚配置待板上验证
无 msh 提示符finsh 未启用确认 RT_USING_FINSH 与 FINSH_USING_MSH 已启用参考说明
启动缓慢时钟未正确初始化检查 CRU 时钟配置，确认 CPU/外设时钟频率待板上验证

3.2 串口通信问题

现象已确认原因处理方法状态
输出乱码波特率不匹配确认收发双方波特率一致（调试串口 1500000）已验证
输出乱码电平不匹配确认 USB 转 TTL 模块为 3.3V 电平，不可接 5V已验证
无法输入命令流控配置错误关闭硬件流控（无流控）参考说明
接收数据丢失接收缓冲区不足增大串口接收缓冲区，或考虑 DMA 模式参考说明
高波特率不稳定信号质量差缩短线缆长度，检查接线，必要时降低波特率待板上验证

3.3 外设驱动问题

现象已确认原因处理方法状态
外设设备找不到设备未注册检查驱动是否编译、注册函数是否执行参考说明
外设设备找不到引脚复用未配置检查 IOMUX 配置（HAL_PINCTRL_SetIOMUX）参考说明
中断不触发中断号配置错误检查中断号与 GIC 配置，注意 AMP 场景 +32 偏移规则待板上验证
外设时钟异常时钟未使能检查 CRU 时钟使能与分频配置待板上验证
DMA 传输失败DMA 通道冲突检查 DMA 通道分配与描述符配置参考说明
I2C/SPI 通信失败总线时序/地址错误检查设备地址、总线速率、片选/ACK 时序参考说明

3.4 内存问题

现象已确认原因处理方法状态
堆内存耗尽内存泄漏使用 free 命令监控，检查 malloc/free 配对参考说明
内存分配失败堆大小不足检查链接脚本堆区域配置，增大堆大小待板上验证
程序莫名崩溃栈溢出检查线程栈大小，使用 list_thread 观察栈水位参考说明
程序崩溃越界访问/野指针使用 SWD 调试定位（详见调试与日志）参考说明
线程间数据错乱临界资源未保护检查信号量/互斥锁使用，确保临界区正确参考说明

3.5 AMP 多核协同问题

现象已确认原因处理方法状态
RTOS 无法启动核心未从 Linux 移除检查 DTS 中是否删除分配给 RTOS 的核心节点待板上验证
RTOS 无法启动共享内存区域冲突检查 reserved-memory 与链接脚本地址是否一致待板上验证
RPMsg 通信失败共享内存地址不匹配核对 Linux 与 RTOS 两侧 RPMsg 地址（_linux_share_rpmsg*）待板上验证
RPMsg 通信失败中断号配置错误验证 amp-irqs 中断号（注意 +32 偏移）待板上验证
外设被 RTOS 独占后 Linux 无法使用外设未正确移交检查 Linux DTS 中外设 status="disabled" 与 pinctrl 移交待板上验证
双系统时钟冲突时钟配置不一致检查两侧 CRU 配置与 DTS clocks 属性一致性待板上验证

详细 AMP 配置参见Linux与RTOS_AMP。

3.6 构建与编译问题

现象已确认原因处理方法状态
scons 命令找不到SCons 未安装安装 SCons（pip install SCons），确认 PATH参考说明
编译报错找不到 BSPRT-Thread 版本不支持 RK3576使用支持 RK3576 的 RT-Thread 版本或 RK3576 AMP SDK待板上验证
编译报错头文件缺失包含路径未配置检查 SConscript 中 CPPPATH 配置参考说明
链接失败（未定义符号）库未链接检查链接脚本与 SConscript 中库依赖参考说明
链接失败（地址越界）内存布局超限检查链接脚本 MEMORY 区域与实际代码大小待板上验证
编译优化导致调试困难优化等级过高调试阶段降低优化等级（如 -O0）参考说明

4. 故障排除工具

4.1 finsh/msh 内置命令

命令用途
list_thread查看线程状态（排查线程卡死）
list_device查看设备注册状态
list_sem/mutex查看同步对象状态
free查看堆内存使用（排查泄漏）
ps查看线程信息

4.2 日志分析方法

  • 通过 rt_kprintf 在关键路径打印日志
  • 使用 ulog 分级日志（LOG_E/W/I/D）便于定位
  • 崩溃时 RT-Thread 会输出异常现场（寄存器/栈回溯），结合地址查符号表

4.3 SWD 在线调试（参考说明）

  • 使用 OpenOCD + GDB 在线调试（方法见调试与日志）
  • 可定位崩溃现场、查看寄存器与内存、设置断点
  • 需确认 C-3576BQ V10 核心板 SWD 引脚位置与 OpenOCD target 配置（待板上验证）

5. 常见问题

Q1: 复位后串口完全无输出，怎么排查？

从硬件到软件逐层排查：

  1. 确认电源正常（5V 典型，见电源管理）
  2. 确认 USB 转 TTL 模块连接正确（TX→RXD、RX→TXD、GND→GND，3.3V 电平）
  3. 确认串口终端波特率 1500000
  4. 确认镜像已烧录/加载到正确地址
  5. 使用 SWD 调试确认程序是否运行

Q2: RT-Thread 启动日志停留在版权信息后无输出？

  • 板级初始化阶段卡死，重点检查 rt_hw_board_init()
  • 时钟初始化是否完成（CRU 配置）
  • 引脚复用配置是否阻塞（IOMUX）
  • 使用 SWD 调试查看程序 PC 指针位置

Q3: 外设驱动注册成功但设备找不到？

  • 检查驱动注册函数是否被调用（INIT_BOARD_EXPORT/INIT_DEVICE_EXPORT）
  • 检查设备名称是否与 rt_device_find 参数一致
  • 检查 menuconfig 中对应驱动组件是否启用

Q4: 程序运行一段时间后崩溃？

  • 大概率是内存问题：堆泄漏、栈溢出、越界访问
  • 使用 free 与 list_thread 监控资源使用趋势
  • 检查临界区资源保护（信号量/互斥锁）
  • 使用 SWD 调试获取崩溃现场

Q5: AMP 模式下 RTOS 起不来？

  • 确认 Linux DTS 已删除分配给 RTOS 的核心节点
  • 确认 reserved-memory 地址与 RTOS 链接脚本一致
  • 确认 amp-irqs 中断号正确（+32 偏移）
  • 确认外设 pinctrl/clocks 已正确移交（详见Linux与RTOS_AMP）

Q6: 编译通过但烧录后不运行？

  • 检查烧录方式是否正确（详见系统烧录指南）
  • 检查镜像加载地址是否与链接脚本入口一致
  • 确认 U-Boot 环境变量配置正确

6. 相关文档

文档说明
RT-Thread环境与工程入口AMP 架构、SDK 目录、构建流程入口
BSP与启动调试串口配置、menuconfig、finsh shell
调试与日志RTOS 调试与日志方法
Linux与RTOS_AMPLinux + RTOS AMP 多核异构方案
电源管理电源规格（5V 典型，最大 5.5V）
系统烧录指南烧录工具与 LOADER 模式