调试方式总览启动阶段主要手段能否源码级断点文档依据BROM / PBP串口日志、USB 烧录、JTAG 停核BROM 基本不可PBP 视方案客制化启动、GDBtinySPL串口 Shell、JTAGGDB、升级调试开关可以测试指南、GDB、启用调试Application串口、JTAGGDB、VSCode可以GDB、BringUp 控制台深度层交互层观察层串口日志AiBurn / aicupgtinySPL 命令行JTAG DebugServer GDBBROMPBPSPLAPP一、全阶段通用串口调试口BootLoader 和 RT-Thread共用一路 UARTBringUp 时必须先配好否则各阶段都看不到日志。1.1 BootLoader 侧bm# 进入 BootLoader 的 menuconfig配置示例Board options --- [*] Using Uart0 Uart0 Parameter --- Bootloader options --- Console --- (0) Console UART ID1.2 RT-Thread 侧me# 或 menuconfigBoard options --- [*] Using Uart0 Rt-Thread options --- RT-Thread Kernel --- Kernel Device Object --- (uart0) the device name for console1.3 pinmux在target/chip/board/pinmux.c里为 UART 配复用与原理图一致。1.4 使用注意波特率默认115200GDB 文档示例用 Tabby / 任意串口工具。Boot 与 App 的UART ID、引脚必须一致否则会出现“Boot 有打印、进系统后没输出”之类问题。参考topics/sdk/bringup/lite-bringup-console.html二、BROM / PBP 阶段这两级在芯片 ROM 或极早期环境运行没有完整 Shell调试以观察和烧录为主。2.1 串口看 PBP 是否跑通上电后若配置了 PBP串口可能出现类似输出GDB 文档中的示例Pre-Boot Program ... (...) No DDR info Going to init DDR2. freq: 504MHz DDR2 initialized PBP done有PBP done说明内存初始化链路过关。卡住或反复复位查 PBP 配置d13x.pbp、pbp_cfg.json、供电与存储介质。2.2 BROM 直启 / 客制化程序用mk_image.py打.aic核对load address ≥ 0x30044000、头 256 字节等约束。烧录AiBurnBROM USB 模式或 VSCode 插件Flash ImageF8板子进 BROM 升级模式 USB 连接。现象判断完全无反应 → 镜像格式/地址能进 USB 但起不来 → 加载地址或 PSRAM 未初始化。参考topics/sdk/d13x_bare_boot/、topics/sdk/env/lite-compile-vscode-extension.html2.3 JTAG早期停核BROM 内几乎不能按应用方式单步。可在tinySPL 已停住时连 JTAG用 GDB 看更早的寄存器/内存或复位瞬间 attach依赖 DebugServer 能力。文档中的标准 JTAG 流程是在CtrlC 进入aictinySPL #之后再连 DebugServer。2.4 此阶段限制D13xBROM 运行时CPU24 MHz、无 Cache、无中断→ 大镜像加载慢且 NAND/eMMC 直载有大小上限大程序应走 tinySPL。参考topics/sdk/d13x_bare_boot/brom-load-limit-and-notes.html三、tinySPLBootLoader阶段 — 文档最完整这是启动链里最适合动手调试的一级。3.1 进入交互命令行最重要文档给出三种进入aictinySPL #的方式方式操作主动中断上电时一直按住 CtrlC焦点在串口窗口被动进入加载 Application 失败自动掉进 Shell升级中断USB/SD 升级过程中CtrlC中止GDB 文档推荐流程串口工具打开波特率 115200焦点放在串口窗口按住 CtrlC 同时上电看到aictinySPL #后再连 JTAG示例输出tinySPL [Built on ...] Boot device 5(BD_SPINAND) nand read speed: ... aictinySPL #3.2 打开 Boot 调试相关编译选项bm# 或 scons --apply-defxxx_baremetal_bootloader_defconfig 后 scons --menuconfigBootloader options --- bootloader debug --- [*] aicupg debug on # USB 升级过程额外调试信息同时打开需要的Boot 命令lite_boot_test_guide.htmlBootloader options --- Bootloader commands --- [*] nor boot [*] nand boot [ ] mmc boot [*] spinor [*] spinand [*] mtd read/write [*] memnor_boot/nand_boot手动试启动mtd读写在 Flash 指定分区核对镜像是否烧对mem查内存内容aicupg debugUSB 烧录协议排错参考topics/sdk/boot/lite_boot_debug_guide.html、lite_boot_test_guide.html3.3 Shell 命令用法进入aictinySPL #后help # 当前已编译进来的命令列表 nor_boot help # 某条命令的用法示例 mtd help按设计main 会执行bootcmd如nor_boot失败才进交互也可在 Shell 里手动执行nor_boot nand_boot mmc_boot aicupg usb 0 # USB 升级调试升级流程时参考topics/sdk/boot/lite_boot_design_guide.html中console_set_bootcmd/console_loop流程。3.4 JTAG GDB 调试 tinySPL / App工具链文档表格工具作用T-Head DebugServerGDB ServerAIC-JTAG硬件调试器toolchain/.../riscv64-unknown-elf-gdbGDB 客户端AiBurn烧录Tabby 等串口硬件与 SDK 准备安装 T-Head DebugServerUSB 连接 AIC-JTAGpinmux.c中配置JTAG 引脚示例为 PA.8~PA.11 复用功能 6menuconfig 关闭与 JTAG冲突的外设如 I2C3、Touch硬件上断开 CTP 排线编译并烧录完整镜像连接步骤要点串口CtrlC 上电→ 停在aictinySPL #启动 DebugServer配置端口如3333连接成功显示本地 IP:端口GDB 连接并加载带符号的 elf仅编 Boot 时mu# 或 ms只编 bootloader# elf 一般在# output/board_baremetal_bootloader/images/*.elfLinux 脚本示例把路径改成你的 Boot 或 App 工程# jtag-debug.shtarget remote172.16.31.141:3333 load ./output/d13x_demo88-nor_baremetal_bootloader/images/d13x.elffile./output/d13x_demo88-nor_baremetal_bootloader/images/d13x.elf./toolchain/bin/riscv64-unknown-elf-gdb-x./jtag-debug.sh调试Application时将load/file指向 RT-Thread 方案的output/.../images/d13x.elf即可。参考topics/sdk/advanced/gdb.html3.5 单独编译 / 迭代 Bootlunchapp方案编号# 先选板级应用方案bm# 改 Boot 配置mu# 只编 Boot → bootloader.binm / mb# 编 App 并打包镜像会用到 pack 里的 bootloader.binBoot 产物output/xxx_baremetal_bootloader/images/与target/chip/board/pack/bootloader.bin分区未变且已有 bootloader.bin时可只ma编应用不必每次重编 Boot参考topics/sdk/boot/lite_boot_config_guide.html、onestep_command_ref.html3.6 USB / SD / U 盘升级流程调试场景配置项调试手段PC USB 烧录aicupg usb upgradeaicupg debug onAiBurn / VSCode Flash看升级日志SD 卡工厂烧录Upgrading by SD Card根目录放镜像 bootcfg.txt勿开会干扰 SDMC 的中断U 盘烧录aicupg udisk upgrade on同上烧完需拔设备再上电注意SD/U 盘烧录完成后不会自动重启避免重复进烧录模式。参考topics/sdk/advanced/burn-procedure-by-diff-media.html四、ApplicationRT-Thread阶段Boot 成功跳转后调试方式与常规 RT-Thread 一致。4.1 串口msh/finsh命令行printk、ulog 等若 Boot 正常而 App 无输出查console 设备名、链接脚本、分区 os 是否正确4.2 JTAG GDB可不在 Boot 停住直接连 DebugServer 对已运行的 App做loadcontinue或在 Boot 阶段 CtrlC 停住后加载App 的 elf再continue过跳转点VSCode安装 C/C 插件配合 Luban-Lite 插件编译GDB 仍通过 DebugServer4.3 与启动相关的 App 侧问题现象建议反复进 Boot Shell故意 CtrlC 或nor_boot失败查 os 分区、镜像头、加载地址OTA 后起不来查 A/B 分区与环境变量OTA 结束需rt_hw_cpu_reset()XIP 方案异常Boot 需先配 XIP 寄存器与 NOR 时序见 XIP 文档五、按问题类型的推荐路径你想查什么推荐做法有没有跑到 tinySPL串口看tinySPLbanner或 CtrlC 能否进#PSRAM/DDR 是否初始化串口看PBP done客制化镜像是否带pbpresourceFlash 里 Boot/App 是否正确tinySPL 下mtd read或离线读 Flashnor_boot为何失败Shell 里手动nor_boot开spinor/mtd对照分区表USB 烧录失败aicupg debug on AiBurn板子是否 BROM 模式Boot 源码断点mu编 elf → CtrlC 停 SPL → JTAG loadbootloaderelfApp 源码断点烧录后 JTAG loadrt-threadelf或 VSCode DebugServer六、推荐的最小调试环境一路 UARTBoot/App 同一 UART、pinmux、115200编译 Boot 命令集bm→ 打开nor_boot、mtd、mem习惯 CtrlC 停 SPL再连 JTAG避免 Boot 自动跳进 App两套 elf 路径记清*_baremetal_bootloader/images/*.elf*_rt-thread_*/images/*.elf升级问题开aicupg debug on用 AiBurn 或aicupg命令七、相关文档索引主题路径启用 Boot 调试开关topics/sdk/boot/lite_boot_debug_guide.htmlBoot 命令行测试topics/sdk/boot/lite_boot_test_guide.htmlBoot 配置与单独编译topics/sdk/boot/lite_boot_config_guide.html启动流程与 bootcmdtopics/sdk/boot/lite_boot_design_guide.htmlJTAG/GDB 全流程topics/sdk/advanced/gdb.htmlBringUp 串口topics/sdk/bringup/lite-bringup-console.htmlOneStepbm/mu/m/aicupgtopics/sdk/advanced/onestep_command_ref.htmlSD/U 盘烧录调试注意topics/sdk/advanced/burn-procedure-by-diff-media.html
D13X调试全攻略：从BROM到应用
调试方式总览启动阶段主要手段能否源码级断点文档依据BROM / PBP串口日志、USB 烧录、JTAG 停核BROM 基本不可PBP 视方案客制化启动、GDBtinySPL串口 Shell、JTAGGDB、升级调试开关可以测试指南、GDB、启用调试Application串口、JTAGGDB、VSCode可以GDB、BringUp 控制台深度层交互层观察层串口日志AiBurn / aicupgtinySPL 命令行JTAG DebugServer GDBBROMPBPSPLAPP一、全阶段通用串口调试口BootLoader 和 RT-Thread共用一路 UARTBringUp 时必须先配好否则各阶段都看不到日志。1.1 BootLoader 侧bm# 进入 BootLoader 的 menuconfig配置示例Board options --- [*] Using Uart0 Uart0 Parameter --- Bootloader options --- Console --- (0) Console UART ID1.2 RT-Thread 侧me# 或 menuconfigBoard options --- [*] Using Uart0 Rt-Thread options --- RT-Thread Kernel --- Kernel Device Object --- (uart0) the device name for console1.3 pinmux在target/chip/board/pinmux.c里为 UART 配复用与原理图一致。1.4 使用注意波特率默认115200GDB 文档示例用 Tabby / 任意串口工具。Boot 与 App 的UART ID、引脚必须一致否则会出现“Boot 有打印、进系统后没输出”之类问题。参考topics/sdk/bringup/lite-bringup-console.html二、BROM / PBP 阶段这两级在芯片 ROM 或极早期环境运行没有完整 Shell调试以观察和烧录为主。2.1 串口看 PBP 是否跑通上电后若配置了 PBP串口可能出现类似输出GDB 文档中的示例Pre-Boot Program ... (...) No DDR info Going to init DDR2. freq: 504MHz DDR2 initialized PBP done有PBP done说明内存初始化链路过关。卡住或反复复位查 PBP 配置d13x.pbp、pbp_cfg.json、供电与存储介质。2.2 BROM 直启 / 客制化程序用mk_image.py打.aic核对load address ≥ 0x30044000、头 256 字节等约束。烧录AiBurnBROM USB 模式或 VSCode 插件Flash ImageF8板子进 BROM 升级模式 USB 连接。现象判断完全无反应 → 镜像格式/地址能进 USB 但起不来 → 加载地址或 PSRAM 未初始化。参考topics/sdk/d13x_bare_boot/、topics/sdk/env/lite-compile-vscode-extension.html2.3 JTAG早期停核BROM 内几乎不能按应用方式单步。可在tinySPL 已停住时连 JTAG用 GDB 看更早的寄存器/内存或复位瞬间 attach依赖 DebugServer 能力。文档中的标准 JTAG 流程是在CtrlC 进入aictinySPL #之后再连 DebugServer。2.4 此阶段限制D13xBROM 运行时CPU24 MHz、无 Cache、无中断→ 大镜像加载慢且 NAND/eMMC 直载有大小上限大程序应走 tinySPL。参考topics/sdk/d13x_bare_boot/brom-load-limit-and-notes.html三、tinySPLBootLoader阶段 — 文档最完整这是启动链里最适合动手调试的一级。3.1 进入交互命令行最重要文档给出三种进入aictinySPL #的方式方式操作主动中断上电时一直按住 CtrlC焦点在串口窗口被动进入加载 Application 失败自动掉进 Shell升级中断USB/SD 升级过程中CtrlC中止GDB 文档推荐流程串口工具打开波特率 115200焦点放在串口窗口按住 CtrlC 同时上电看到aictinySPL #后再连 JTAG示例输出tinySPL [Built on ...] Boot device 5(BD_SPINAND) nand read speed: ... aictinySPL #3.2 打开 Boot 调试相关编译选项bm# 或 scons --apply-defxxx_baremetal_bootloader_defconfig 后 scons --menuconfigBootloader options --- bootloader debug --- [*] aicupg debug on # USB 升级过程额外调试信息同时打开需要的Boot 命令lite_boot_test_guide.htmlBootloader options --- Bootloader commands --- [*] nor boot [*] nand boot [ ] mmc boot [*] spinor [*] spinand [*] mtd read/write [*] memnor_boot/nand_boot手动试启动mtd读写在 Flash 指定分区核对镜像是否烧对mem查内存内容aicupg debugUSB 烧录协议排错参考topics/sdk/boot/lite_boot_debug_guide.html、lite_boot_test_guide.html3.3 Shell 命令用法进入aictinySPL #后help # 当前已编译进来的命令列表 nor_boot help # 某条命令的用法示例 mtd help按设计main 会执行bootcmd如nor_boot失败才进交互也可在 Shell 里手动执行nor_boot nand_boot mmc_boot aicupg usb 0 # USB 升级调试升级流程时参考topics/sdk/boot/lite_boot_design_guide.html中console_set_bootcmd/console_loop流程。3.4 JTAG GDB 调试 tinySPL / App工具链文档表格工具作用T-Head DebugServerGDB ServerAIC-JTAG硬件调试器toolchain/.../riscv64-unknown-elf-gdbGDB 客户端AiBurn烧录Tabby 等串口硬件与 SDK 准备安装 T-Head DebugServerUSB 连接 AIC-JTAGpinmux.c中配置JTAG 引脚示例为 PA.8~PA.11 复用功能 6menuconfig 关闭与 JTAG冲突的外设如 I2C3、Touch硬件上断开 CTP 排线编译并烧录完整镜像连接步骤要点串口CtrlC 上电→ 停在aictinySPL #启动 DebugServer配置端口如3333连接成功显示本地 IP:端口GDB 连接并加载带符号的 elf仅编 Boot 时mu# 或 ms只编 bootloader# elf 一般在# output/board_baremetal_bootloader/images/*.elfLinux 脚本示例把路径改成你的 Boot 或 App 工程# jtag-debug.shtarget remote172.16.31.141:3333 load ./output/d13x_demo88-nor_baremetal_bootloader/images/d13x.elffile./output/d13x_demo88-nor_baremetal_bootloader/images/d13x.elf./toolchain/bin/riscv64-unknown-elf-gdb-x./jtag-debug.sh调试Application时将load/file指向 RT-Thread 方案的output/.../images/d13x.elf即可。参考topics/sdk/advanced/gdb.html3.5 单独编译 / 迭代 Bootlunchapp方案编号# 先选板级应用方案bm# 改 Boot 配置mu# 只编 Boot → bootloader.binm / mb# 编 App 并打包镜像会用到 pack 里的 bootloader.binBoot 产物output/xxx_baremetal_bootloader/images/与target/chip/board/pack/bootloader.bin分区未变且已有 bootloader.bin时可只ma编应用不必每次重编 Boot参考topics/sdk/boot/lite_boot_config_guide.html、onestep_command_ref.html3.6 USB / SD / U 盘升级流程调试场景配置项调试手段PC USB 烧录aicupg usb upgradeaicupg debug onAiBurn / VSCode Flash看升级日志SD 卡工厂烧录Upgrading by SD Card根目录放镜像 bootcfg.txt勿开会干扰 SDMC 的中断U 盘烧录aicupg udisk upgrade on同上烧完需拔设备再上电注意SD/U 盘烧录完成后不会自动重启避免重复进烧录模式。参考topics/sdk/advanced/burn-procedure-by-diff-media.html四、ApplicationRT-Thread阶段Boot 成功跳转后调试方式与常规 RT-Thread 一致。4.1 串口msh/finsh命令行printk、ulog 等若 Boot 正常而 App 无输出查console 设备名、链接脚本、分区 os 是否正确4.2 JTAG GDB可不在 Boot 停住直接连 DebugServer 对已运行的 App做loadcontinue或在 Boot 阶段 CtrlC 停住后加载App 的 elf再continue过跳转点VSCode安装 C/C 插件配合 Luban-Lite 插件编译GDB 仍通过 DebugServer4.3 与启动相关的 App 侧问题现象建议反复进 Boot Shell故意 CtrlC 或nor_boot失败查 os 分区、镜像头、加载地址OTA 后起不来查 A/B 分区与环境变量OTA 结束需rt_hw_cpu_reset()XIP 方案异常Boot 需先配 XIP 寄存器与 NOR 时序见 XIP 文档五、按问题类型的推荐路径你想查什么推荐做法有没有跑到 tinySPL串口看tinySPLbanner或 CtrlC 能否进#PSRAM/DDR 是否初始化串口看PBP done客制化镜像是否带pbpresourceFlash 里 Boot/App 是否正确tinySPL 下mtd read或离线读 Flashnor_boot为何失败Shell 里手动nor_boot开spinor/mtd对照分区表USB 烧录失败aicupg debug on AiBurn板子是否 BROM 模式Boot 源码断点mu编 elf → CtrlC 停 SPL → JTAG loadbootloaderelfApp 源码断点烧录后 JTAG loadrt-threadelf或 VSCode DebugServer六、推荐的最小调试环境一路 UARTBoot/App 同一 UART、pinmux、115200编译 Boot 命令集bm→ 打开nor_boot、mtd、mem习惯 CtrlC 停 SPL再连 JTAG避免 Boot 自动跳进 App两套 elf 路径记清*_baremetal_bootloader/images/*.elf*_rt-thread_*/images/*.elf升级问题开aicupg debug on用 AiBurn 或aicupg命令七、相关文档索引主题路径启用 Boot 调试开关topics/sdk/boot/lite_boot_debug_guide.htmlBoot 命令行测试topics/sdk/boot/lite_boot_test_guide.htmlBoot 配置与单独编译topics/sdk/boot/lite_boot_config_guide.html启动流程与 bootcmdtopics/sdk/boot/lite_boot_design_guide.htmlJTAG/GDB 全流程topics/sdk/advanced/gdb.htmlBringUp 串口topics/sdk/bringup/lite-bringup-console.htmlOneStepbm/mu/m/aicupgtopics/sdk/advanced/onestep_command_ref.htmlSD/U 盘烧录调试注意topics/sdk/advanced/burn-procedure-by-diff-media.html
