调试与日志

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

1. 概述

本文档介绍 M4-R2（RK3576）平台上 RT-Thread 系统的调试与日志方法，涵盖调试串口、finsh/msh shell、日志系统（rt_kprintf / ulog）、内存调试以及 SWD/JTAG 在线调试等。

文档范围：

  • 调试串口（底板 DEBUG 串口，1500000bps）
  • finsh/msh 交互式 shell
  • 日志系统（rt_kprintf / ulog 日志框架）
  • 内存与线程调试命令
  • SWD 在线调试（GNU MCU Eclipse OpenOCD，参考说明）
  • Ymodem 文件传输（ry/sy 命令，参考说明）

调试串口硬件事实（已验证）：底板 DEBUG 串口为 4pin/1.0mm 连接器，3.3V 电平，波特率 1500000bps。底板原理图（S-04）中调试串口网络标注为 UART0_TX_M0_DEBUG（GPIO0_D4_D）/UART0_RX_M0_DEBUG（GPIO0_D5_D）。规格书（S-01）将调试串口标为 UART2（RX2/TX2），两者命名不一致，具体以实际物料与 SDK 配置为准（待板上验证）。

参考说明：本文档调试工具与方法基于 Rockchip 官方通用 RT-Thread 调试指南编写，RK3576 平台的具体支持情况以实际发布的 RK3576 AMP SDK 为准。

2. 硬件准备

2.1 调试串口连接

信号底板引脚USB 转 TTL 引脚
TXUART0_TX_M0_DEBUG（DEBUG 串口）RXD
RXUART0_RX_M0_DEBUG（DEBUG 串口）TXD
GNDGNDGND

来源：S-04 底板原理图 / S-06 IO Domains（已验证） 注意：调试串口为 3.3V 电平，使用 USB 转 TTL 模块时确认电平匹配，切勿直接接 5V。

2.2 SWD 调试接口（参考说明）

C-3576BQ V10 核心板提供 SWD 调试接口（具体引出引脚与排针位置以核心板实物和原理图为准，待板上确认）：

信号说明
SWCLKSWD 时钟线
SWDIOSWD 数据线
GND地

参考说明：RK3576 支持 ARM 标准 SWD（Serial Wire Debug）接口，可通过 OpenOCD 连接进行在线调试。核心板 SWD 引脚具体位置以 C-3576BQ V10 核心板实物与原理图为准（待板上确认）。

2.3 必要工具

工具用途
USB 转 TTL 模块（3.3V）连接调试串口
串口终端软件PuTTY / minicom / MobaXterm
GNU MCU Eclipse OpenOCDSWD 在线调试（参考说明）
Ymodem 传输工具通过串口传输文件（参考说明）

3. 软件准备

3.1 调试相关配置

在 menuconfig 中启用调试与日志相关组件：

RT-Thread Components →
  Finsh Shell →
    [*] Using finsh shell             # RT_USING_FINSH=y
    [*] Using MSH shell               # FINSH_USING_MSH=y
    (4096) The stack size of finsh thread   # CONFIG_FINSH_THREAD_STACK_SIZE=4096
  Logging →
    [*] Enable log buffer            # RT_USING_ULOG=y（可选用 ulog 日志框架）

3.2 defconfig 相关配置项

CONFIG_RT_USING_FINSH=y          # 启用 finsh shell
CONFIG_FINSH_USING_MSH=y         # 启用 MSH shell
CONFIG_FINSH_THREAD_STACK_SIZE=4096
CONFIG_RT_USING_ULOG=y           # 启用 ulog 日志（可选）
CONFIG_RT_USING_HEAP=y           # 启用堆内存（内存调试需要）

3.3 调试工具链（参考说明）

  • GNU MCU Eclipse OpenOCD（SWD 调试，参考说明）
  • 对应 ARM Cortex-A 内核的 GDB（如 arm-none-eabi-gdb，以实际工具链为准）

4. 操作步骤

4.1 通过调试串口连接 RT-Thread

  1. 连接 USB 转 TTL 模块到底板 DEBUG 串口
  2. 打开串口终端软件（如 PuTTY）
  3. 设置波特率 1500000（与底板调试串口一致）
  4. 数据位 8、停止位 1、无校验、无流控
  5. 复位开发板，等待启动日志输出
Starting kernel ...
Welcome to RT-Thread
...
msh />

出现 msh /> 提示符即表示 RT-Thread shell 已就绪。

4.2 常用 shell 命令

命令功能
help查看所有可用命令
list_thread列出所有线程及其状态
list_device列出所有设备
list_timer列出所有定时器
list_sem列出所有信号量
list_mutex列出所有互斥锁
list_mempool列出所有内存池
list_memheap列出所有内存堆
free查看堆内存使用情况
version查看 RT-Thread 版本信息
ps查看线程与进程信息（MSH）
pin引脚操作命令
ry / syYmodem 接收 / 发送文件（参考说明）

4.3 日志输出配置

RT-Thread 的默认日志输出通过 rt_kprintf 实现，发送到调试串口。可通过 finsh 命令动态调整日志级别（ulog 框架）：

msh /> log_lvl 3          # 设置日志级别（3=INFO，以实际 ulog 命令为准）
msh /> log_show           # 查看日志配置

参考说明：ulog 日志框架的具体命令与配置项以 RT-Thread 版本为准。

4.4 Ymodem 文件传输（参考说明）

RT-Thread 支持通过 Ymodem 协议在调试串口传输文件：

msh /> sy test.bin        # 从串口发送文件（Ymodem）
msh /> ry                 # 从串口接收文件（Ymodem）

参考说明：Ymodem 传输使用 CRC16 校验。具体命令参数与实现以 RT-Thread 版本为准。

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

4.5.1 OpenOCD 启动

使用 GNU MCU Eclipse OpenOCD 连接 SWD 调试接口（配置以实际目标板为准）：

openocd -f interface/stlink-v2.cfg -f target/rk3576.cfg

注意：需要针对 RK3576 编写/获取对应的 OpenOCD target 配置文件（以实际发布的调试配置为准，待板上验证）。核心板 SWD 引脚位置见本文档 2.2 节。

4.5.2 OpenOCD 常用端口

端口用途
4444Telnet 控制端口
3333GDB 远程调试端口

4.5.3 GDB 连接

# 启动 GDB
arm-none-eabi-gdb rtthread.elf

# 在 GDB 中连接 OpenOCD
(gdb) target remote localhost:3333

# 常用命令
(gdb) load              # 加载程序
(gdb) continue          # 继续执行
(gdb) break main        # 设置断点
(gdb) info registers    # 查看寄存器
(gdb) monitor reset     # 复位目标板

4.5.4 SWD 速度建议（参考说明）

模式最高速度推荐速度
SWD30 MHz15 MHz / 7.5 MHz

参考说明：SWD 速度根据实际线缆长度与目标板情况调整，信号不稳定时降低速度。上述数值为 Rockchip 通用调试指南参考值，非 RK3576 实测数据。

5. 代码详解

5.1 rt_kprintf 日志输出

#include <rtthread.h>

void log_example(void)
{
    /* 基础日志输出 */
    rt_kprintf("Hello, M4-R2!\n");

    /* 带格式的日志输出 */
    rt_kprintf("Thread name: %s, priority: %d\n", "demo", 10);

    /* 十六进制输出 */
    rt_kprintf("Register value: 0x%08X\n", 0x12345678);
}

5.2 ulog 日志框架（可选）

#include <rtdbg.h>

#define DBG_TAG "example"
#define DBG_LVL DBG_INFO

void ulog_example(void)
{
    LOG_E("error message");    /* 错误级别 */
    LOG_W("warning message");  /* 警告级别 */
    LOG_I("info message");     /* 信息级别 */
    LOG_D("debug message");    /* 调试级别 */
}

5.3 内存调试示例

#include <rtthread.h>

void mem_debug_example(void)
{
    /* 查看堆内存使用情况 */
    struct rt_memory_info info;
    rt_memory_info(&info);
    rt_kprintf("Total: %d, Used: %d, Max used: %d\n",
               info.total_memory, info.used_memory, info.max_used_memory);

    /* 内存泄漏检测（配置 RT_USING_MEMTRACE 后） */
    /* 通过 finsh 命令 memtrace 查看内存分配跟踪 */
}

5.4 线程调试示例

#include <rtthread.h>

void thread_debug_example(void)
{
    /* 列出所有线程 */
    rt_thread_control(rt_thread_self(), RT_THREAD_CTRL_INFO, RT_NULL);
    /* 更简便的方式：在 shell 中使用 list_thread 命令 */

    /* 查看当前线程名称 */
    rt_kprintf("Current thread: %s\n", rt_thread_self()->name);
}

5.5 断言与异常处理

#include <rtthread.h>

void assert_example(void)
{
    int value = 100;

    /* 断言：条件为假时触发 */
    RT_ASSERT(value < 200);

    /* 触发硬件错误（测试用） */
    /* 当出现异常时，RT-Thread 会输出异常信息并进入中断处理 */
}

6. 常见问题

6.1 串口无输出

现象原因处理方法
串口终端无输出波特率设置不正确确认设置为 1500000（与底板调试串口一致）
串口终端无输出调试串口未选为控制台设备检查 menuconfig 中 console 配置
输出乱码电平不匹配确认 USB 转 TTL 模块为 3.3V 电平

6.2 finsh shell 无法交互

现象原因处理方法
无 msh 提示符finsh/msh 未启用确认 RT_USING_FINSH 与 FINSH_USING_MSH 已启用
输入命令无响应shell 线程优先级过低检查 finsh 线程优先级与栈大小配置
命令执行卡死栈空间不足增大 CONFIG_FINSH_THREAD_STACK_SIZE

6.3 内存问题

现象原因处理方法
堆内存耗尽内存泄漏使用 free 命令监控，检查内存分配释放配对
内存分配失败堆大小配置不足检查链接脚本中堆大小配置
程序崩溃越界访问 / 野指针使用 SWD 调试定位，检查数组越界与指针初始化

6.4 SWD 调试问题（参考说明）

现象原因处理方法
OpenOCD 连接失败接线错误 / 速度过高检查 SWCLK/SWDIO/GND 接线，降低 SWD 速度
GDB 无法加载程序镜像格式不匹配确认加载的是 ELF 格式镜像（rtthread.elf）
断点不生效位置无关代码 / 优化编译时关闭优化或使用硬件断点

7. 相关文档

文档说明
RT-Thread环境与工程入口AMP 架构、SDK 目录、构建流程入口
BSP与启动调试串口配置、menuconfig、finsh shell
Linux与RTOS_AMPLinux + RTOS AMP 多核异构方案
故障排除RTOS 常见问题与故障排除
核心板参数调试串口引脚、核心板规格等硬件事实
系统烧录指南烧录工具与 LOADER 模式
调试工具使用指南Linux 侧调试方法（对照参考）