衡山派开发板GDB调试实战基于T-HeadDebugServer与AIC-JTAG的JTAG/SDMC接口配置详解最近在用衡山派开发板基于玄铁RISC-V处理器做项目调试程序时发现虽然知道要用GDB但具体怎么把硬件连起来、软件怎么配网上的资料比较零散。今天我就把自己折腾了好几天才搞定的完整调试方案分享出来手把手教你用T-HeadDebugServer和AIC-JTAG调试器在Luban-Lite SDK环境下搭建调试环境。不管你是用JTAG口还是SDMC口跟着做一遍就能搞定。1. 调试工具全家福认识你的“装备”工欲善其事必先利其器。在开始接线和配置之前咱们先得搞清楚要用到哪些工具别到时候手忙脚乱。下面这个表格是我整理的工具清单你照着准备就行。工具说明T-HeadDebugServer核心工具运行在电脑上的GDB Server负责和调试器、开发板通信。AiBurn镜像烧写工具用来把编译好的程序刷到开发板里。AIC-JTAG硬件调试器连接电脑和开发板的桥梁。JTAG - SDMC 转接线注意这个线只有在你使用SDMC接口进行调试时才需要用JTAG口调试不需要它。Eclipse官方适配Luban-Lite SDK的IDE在Windows下图形化调试很方便。riscv64-unknown-elf-gdb.exe命令行调试工具在Linux下或喜欢命令行的朋友会用到。它在SDK的tool/riscv64-gdb/bin/目录下。d21x.elf你的工程编译后生成的带调试符号的文件在Eclipse工程目录下能找到。Tabby一个串口终端工具用来查看开发板的调试串口输出并发送指令。提示T-HeadDebugServer的安装包通常已经包含了AIC-JTAG调试器的驱动安装时一起搞定省心。2. 第一步安装调试服务器与连接硬件2.1 安装T-HeadDebugServer找到T-HeadDebugServer的安装包通常是一个压缩文件解压。运行解压出来的setup.exe。安装过程很常规点击“Next” - 在用户协议界面点击“Yes” - 可以修改安装路径不改也行 - 在安装内容页面建议把组件全选上然后继续“Next”。等待安装完成桌面上会自动出现一个“DebugServer”的快捷方式。2.2 连接AIC-JTAG调试器用USB-TypeC线将AIC-JTAG调试器连接到你的电脑。连接成功后调试器上的绿灯会亮起这表示电脑已经识别到它了。如果灯没亮检查一下线缆和USB口。3. SDK配置为调试“铺路”Luban-Lite SDK支持通过JTAG和SDMC两种物理接口进行调试。为了避免调试接口和板子上其他功能比如触摸屏、SD卡的GPIO引脚冲突我们必须先对SDK进行一些配置。重要在进行下面的配置之前请确保你已经通过scons --menuconfig加载了你想要调试的目标工程配置文件。3.1 使用JTAG接口调试如果你打算使用标准的JTAG接口通常是那个排针接口配置相对简单。配置菜单选项在SDK根目录下打开终端运行配置命令scons --menuconfig在出现的图形化配置界面中需要关闭可能与JTAG引脚冲突的功能进入Board options ---找到[ ] Using i2c3取消它的选中按空格键。进入Drivers options --- Peripheral --- Touch Panel Support --- Gt911 touch panel options ---找到[ ] Using touch panel gt911取消它的选中。注意如果你实际使用了JTAG口进行调试物理上还需要断开开发板上连接CTP电容触摸屏的排线以防硬件冲突。3.2 使用SDMC接口调试SDMC口其实就是SD卡接口复用成了调试功能。它的配置稍微复杂一点需要修改一个配置文件。修改DDR初始化配置文件找到并打开你当前工程对应的DDR初始化配置文件路径通常是target/CPU/board/pack/ddr_init.json请将CPU和board替换为你实际使用的芯片和板型如d13x、demo88等。在这个JSON文件中找到jtag配置段。你需要做两件事将jtag_only的值设置为1。这个设置会让Boot代码在初始化完DDR和JTAG后暂停等待调试器连接。将JTAG引脚配置注释掉并启用SDMC对应的引脚配置。关键就在这里原始文件里可能已经提供了两组配置一组是JTAG的被注释了一组是SDMC的。你需要确保使用的是下面这组PC0-PC5jtag: { jtag_only: 1, // 1: Boot code stop in PBP after DDR init and jtag init main: { jtag_id: 0, // 以下是SDMC接口对应的JTAG引脚配置 (PC0, PC1, PC3, PC5) jtag_do_pin_cfg_reg: 0x1870028C, // PC3 jtag_do_pin_cfg_val: 0x336, jtag_di_pin_cfg_reg: 0x18700284, // PC1 jtag_di_pin_cfg_val: 0x336, jtag_ms_pin_cfg_reg: 0x18700280, // PC0 jtag_ms_pin_cfg_val: 0x336, jtag_ck_pin_cfg_reg: 0x18700294, // PC5 jtag_ck_pin_cfg_val: 0x336, }, },如果文件里jtag_do_pin_cfg_reg等字段指向的是PA8、PA9等地址如0x187000A0那说明是JTAG口的配置你需要把它们注释掉并取消上面PC口配置的注释。配置菜单选项同样运行scons --menuconfig这次需要关闭SDMC1功能防止它被当作SD卡占用。进入Board options ---找到[ ] Using SDMC1取消它的选中。4. 连接与启动让调试器“握手”成功配置好SDK后咱们就要动真格的了把硬件连起来启动调试服务器。编译与烧录在SDK根目录下执行scons编译工程。然后使用AiBurn工具将生成的镜像文件通常是.bin或.img烧录到开发板中。具体烧录方法请参考烧录章节的教程。硬件连接给开发板接上调试串口线、AIC-JTAG调试器和电源线。如果使用SDMC口调试记得接上JTAG-SDMC转接线。启动串口终端打开Tabby选择正确的串口号如COM3设置好波特率通常是115200连接开发板的调试串口。让开发板进入等待调试状态这是关键一步在Tabby的串口窗口点击一下确保光标焦点在这个窗口。按住键盘上的 Ctrl C 不要松开。然后给开发板上电。如果操作成功你会在串口看到类似下面的打印信息说明开发板已经停在Pre-Boot Program阶段等待调试器连接Pre-Boot Program ... (2023-08-08 11:29:35 13a563f) No DDR info Going to init DDR2. freq: 504MHz DDR2 initialized 120186 134875 162258 PBP done tinySPL [Built on Aug 21 2023 17:12:58] Boot device 5(BD_SPINAND) nand read speed: 1346320 byte, 76998 us - 17075 KB/s aictinySPL # aictinySPL #启动并配置DebugServer双击桌面上的“DebugServer”图标运行。首次运行防火墙可能会有安全警告点击“允许访问”。在DebugServer界面点击菜单栏的Setting - Target Setting。在弹出的窗口中配置一个端口号比如默认的3333。点击连接按钮或类似功能启动仿真器连接。如果连接成功界面会显示本地IP地址和你刚才设置的端口号例如172.16.31.141:3333。看到这个IP和端口号恭喜你硬件连接和服务器启动已经成功了接下来就可以用Eclipse或者命令行GDB进行调试了。5. 开始调试Windows与Linux双环境指南5.1 Windows下使用Eclipse调试推荐新手Eclipse提供了图形化界面设置断点、查看变量、单步执行都很直观。注意使用Eclipse调试前你必须已经按照SDK文档中“Eclipse工程导入”章节的步骤成功创建并编译了Eclipse工程。配置调试选项在Eclipse中找到菜单Run - Debug Configurations...。Main标签页创建一个“GDB Hardware Debugging”配置。在“C/C Application”一栏点击“Browse...”选择你工程目录下生成的.elf文件比如d21x.elf。Debugger标签页Debugger: 选择gdbserver。GDB debugger: 浏览并选择SDK工具链里的GDB路径类似$(Your_SDK_Path)/tool/riscv64-gdb/bin/riscv64-unknown-elf-gdb.exe。GDB command file: 可以留空或者创建一个包含基础设置的脚本。Connection标签卡选择“TCP”。在“Host name or IP address”中填入运行DebugServer的电脑的IP在“Port number”中填入DebugServer设置的端口如3333。开始调试点击“Debug”按钮Eclipse就会通过GDB连接到远端的DebugServer。如果一切正常程序会暂停在入口点比如main函数然后你就可以使用下面的快捷键愉快地调试了F5单步进入Step Into进入函数内部。F6单步跳过Step Over执行下一行代码不进入函数。F7单步返回Step Return执行完当前函数返回到调用处。F8继续运行Resume跳到下一个断点。F11启动调试Debug。5.2 Linux下使用命令行GDB调试如果你更习惯在Linux环境下工作或者需要远程调试命令行GDB是你的好帮手。注意在Linux下调试前请确保你的Linux机器能够ping通运行DebugServer的Windows电脑的IP地址。编写GDB连接脚本在SDK的根目录下创建一个名为jtag-debug.sh的脚本文件。#!/bin/bash # 连接到远程的DebugServerIP和端口换成你实际的 target remote 172.16.31.141:3333 # 将调试符号文件elf加载到开发板的内存中 load ./output/d13x_demo88-nor_rt-thread_helloworld/images/d13x.elf # 指定本地用于读取符号的elf文件和load的是同一个 file ./output/d13x_demo88-nor_rt-thread_helloworld/images/d13x.elf记得把里面的IP地址、端口号以及elf文件的路径替换成你项目实际的信息。启动GDB并运行脚本在SDK根目录打开终端执行以下命令./toolchain/bin/riscv64-unknown-elf-gdb -x ./jtag-debug.sh这个命令会启动GDB并自动执行我们刚才写的脚本。连接成功如果一切顺利你会看到GDB启动信息然后脚本执行target remote连接成功接着load命令开始加载程序到板子内存中显示加载进度。当出现类似下面的信息时表示你已经成功进入GDB调试模式可以开始输入GDB命令如break main,continue,step等进行调试了。Loading section .text, size 0xa4780 lma 0x40000100 ... Loading section .rodata, size 0x843b8 lma 0x400a4880 ... Start address 0x0000000040000100, load size 1228312 Transfer rate: 107 KB/sec, 3988 bytes/write. (gdb)到这里整个基于衡山派开发板的GDB调试环境就搭建并连接成功了。无论是用图形化的Eclipse还是命令行的GDB核心都是通过T-HeadDebugServer这个桥梁。实际调试中如果连接失败多半要回头检查第4步的“按住CtrlC上电”操作是否成功以及DebugServer的IP和端口配置是否正确。这个流程我踩过几次坑按这个步骤来基本都能一次成功。
衡山派开发板GDB调试实战：基于T-HeadDebugServer与AIC-JTAG的JTAG/SDMC接口配置详解
衡山派开发板GDB调试实战基于T-HeadDebugServer与AIC-JTAG的JTAG/SDMC接口配置详解最近在用衡山派开发板基于玄铁RISC-V处理器做项目调试程序时发现虽然知道要用GDB但具体怎么把硬件连起来、软件怎么配网上的资料比较零散。今天我就把自己折腾了好几天才搞定的完整调试方案分享出来手把手教你用T-HeadDebugServer和AIC-JTAG调试器在Luban-Lite SDK环境下搭建调试环境。不管你是用JTAG口还是SDMC口跟着做一遍就能搞定。1. 调试工具全家福认识你的“装备”工欲善其事必先利其器。在开始接线和配置之前咱们先得搞清楚要用到哪些工具别到时候手忙脚乱。下面这个表格是我整理的工具清单你照着准备就行。工具说明T-HeadDebugServer核心工具运行在电脑上的GDB Server负责和调试器、开发板通信。AiBurn镜像烧写工具用来把编译好的程序刷到开发板里。AIC-JTAG硬件调试器连接电脑和开发板的桥梁。JTAG - SDMC 转接线注意这个线只有在你使用SDMC接口进行调试时才需要用JTAG口调试不需要它。Eclipse官方适配Luban-Lite SDK的IDE在Windows下图形化调试很方便。riscv64-unknown-elf-gdb.exe命令行调试工具在Linux下或喜欢命令行的朋友会用到。它在SDK的tool/riscv64-gdb/bin/目录下。d21x.elf你的工程编译后生成的带调试符号的文件在Eclipse工程目录下能找到。Tabby一个串口终端工具用来查看开发板的调试串口输出并发送指令。提示T-HeadDebugServer的安装包通常已经包含了AIC-JTAG调试器的驱动安装时一起搞定省心。2. 第一步安装调试服务器与连接硬件2.1 安装T-HeadDebugServer找到T-HeadDebugServer的安装包通常是一个压缩文件解压。运行解压出来的setup.exe。安装过程很常规点击“Next” - 在用户协议界面点击“Yes” - 可以修改安装路径不改也行 - 在安装内容页面建议把组件全选上然后继续“Next”。等待安装完成桌面上会自动出现一个“DebugServer”的快捷方式。2.2 连接AIC-JTAG调试器用USB-TypeC线将AIC-JTAG调试器连接到你的电脑。连接成功后调试器上的绿灯会亮起这表示电脑已经识别到它了。如果灯没亮检查一下线缆和USB口。3. SDK配置为调试“铺路”Luban-Lite SDK支持通过JTAG和SDMC两种物理接口进行调试。为了避免调试接口和板子上其他功能比如触摸屏、SD卡的GPIO引脚冲突我们必须先对SDK进行一些配置。重要在进行下面的配置之前请确保你已经通过scons --menuconfig加载了你想要调试的目标工程配置文件。3.1 使用JTAG接口调试如果你打算使用标准的JTAG接口通常是那个排针接口配置相对简单。配置菜单选项在SDK根目录下打开终端运行配置命令scons --menuconfig在出现的图形化配置界面中需要关闭可能与JTAG引脚冲突的功能进入Board options ---找到[ ] Using i2c3取消它的选中按空格键。进入Drivers options --- Peripheral --- Touch Panel Support --- Gt911 touch panel options ---找到[ ] Using touch panel gt911取消它的选中。注意如果你实际使用了JTAG口进行调试物理上还需要断开开发板上连接CTP电容触摸屏的排线以防硬件冲突。3.2 使用SDMC接口调试SDMC口其实就是SD卡接口复用成了调试功能。它的配置稍微复杂一点需要修改一个配置文件。修改DDR初始化配置文件找到并打开你当前工程对应的DDR初始化配置文件路径通常是target/CPU/board/pack/ddr_init.json请将CPU和board替换为你实际使用的芯片和板型如d13x、demo88等。在这个JSON文件中找到jtag配置段。你需要做两件事将jtag_only的值设置为1。这个设置会让Boot代码在初始化完DDR和JTAG后暂停等待调试器连接。将JTAG引脚配置注释掉并启用SDMC对应的引脚配置。关键就在这里原始文件里可能已经提供了两组配置一组是JTAG的被注释了一组是SDMC的。你需要确保使用的是下面这组PC0-PC5jtag: { jtag_only: 1, // 1: Boot code stop in PBP after DDR init and jtag init main: { jtag_id: 0, // 以下是SDMC接口对应的JTAG引脚配置 (PC0, PC1, PC3, PC5) jtag_do_pin_cfg_reg: 0x1870028C, // PC3 jtag_do_pin_cfg_val: 0x336, jtag_di_pin_cfg_reg: 0x18700284, // PC1 jtag_di_pin_cfg_val: 0x336, jtag_ms_pin_cfg_reg: 0x18700280, // PC0 jtag_ms_pin_cfg_val: 0x336, jtag_ck_pin_cfg_reg: 0x18700294, // PC5 jtag_ck_pin_cfg_val: 0x336, }, },如果文件里jtag_do_pin_cfg_reg等字段指向的是PA8、PA9等地址如0x187000A0那说明是JTAG口的配置你需要把它们注释掉并取消上面PC口配置的注释。配置菜单选项同样运行scons --menuconfig这次需要关闭SDMC1功能防止它被当作SD卡占用。进入Board options ---找到[ ] Using SDMC1取消它的选中。4. 连接与启动让调试器“握手”成功配置好SDK后咱们就要动真格的了把硬件连起来启动调试服务器。编译与烧录在SDK根目录下执行scons编译工程。然后使用AiBurn工具将生成的镜像文件通常是.bin或.img烧录到开发板中。具体烧录方法请参考烧录章节的教程。硬件连接给开发板接上调试串口线、AIC-JTAG调试器和电源线。如果使用SDMC口调试记得接上JTAG-SDMC转接线。启动串口终端打开Tabby选择正确的串口号如COM3设置好波特率通常是115200连接开发板的调试串口。让开发板进入等待调试状态这是关键一步在Tabby的串口窗口点击一下确保光标焦点在这个窗口。按住键盘上的 Ctrl C 不要松开。然后给开发板上电。如果操作成功你会在串口看到类似下面的打印信息说明开发板已经停在Pre-Boot Program阶段等待调试器连接Pre-Boot Program ... (2023-08-08 11:29:35 13a563f) No DDR info Going to init DDR2. freq: 504MHz DDR2 initialized 120186 134875 162258 PBP done tinySPL [Built on Aug 21 2023 17:12:58] Boot device 5(BD_SPINAND) nand read speed: 1346320 byte, 76998 us - 17075 KB/s aictinySPL # aictinySPL #启动并配置DebugServer双击桌面上的“DebugServer”图标运行。首次运行防火墙可能会有安全警告点击“允许访问”。在DebugServer界面点击菜单栏的Setting - Target Setting。在弹出的窗口中配置一个端口号比如默认的3333。点击连接按钮或类似功能启动仿真器连接。如果连接成功界面会显示本地IP地址和你刚才设置的端口号例如172.16.31.141:3333。看到这个IP和端口号恭喜你硬件连接和服务器启动已经成功了接下来就可以用Eclipse或者命令行GDB进行调试了。5. 开始调试Windows与Linux双环境指南5.1 Windows下使用Eclipse调试推荐新手Eclipse提供了图形化界面设置断点、查看变量、单步执行都很直观。注意使用Eclipse调试前你必须已经按照SDK文档中“Eclipse工程导入”章节的步骤成功创建并编译了Eclipse工程。配置调试选项在Eclipse中找到菜单Run - Debug Configurations...。Main标签页创建一个“GDB Hardware Debugging”配置。在“C/C Application”一栏点击“Browse...”选择你工程目录下生成的.elf文件比如d21x.elf。Debugger标签页Debugger: 选择gdbserver。GDB debugger: 浏览并选择SDK工具链里的GDB路径类似$(Your_SDK_Path)/tool/riscv64-gdb/bin/riscv64-unknown-elf-gdb.exe。GDB command file: 可以留空或者创建一个包含基础设置的脚本。Connection标签卡选择“TCP”。在“Host name or IP address”中填入运行DebugServer的电脑的IP在“Port number”中填入DebugServer设置的端口如3333。开始调试点击“Debug”按钮Eclipse就会通过GDB连接到远端的DebugServer。如果一切正常程序会暂停在入口点比如main函数然后你就可以使用下面的快捷键愉快地调试了F5单步进入Step Into进入函数内部。F6单步跳过Step Over执行下一行代码不进入函数。F7单步返回Step Return执行完当前函数返回到调用处。F8继续运行Resume跳到下一个断点。F11启动调试Debug。5.2 Linux下使用命令行GDB调试如果你更习惯在Linux环境下工作或者需要远程调试命令行GDB是你的好帮手。注意在Linux下调试前请确保你的Linux机器能够ping通运行DebugServer的Windows电脑的IP地址。编写GDB连接脚本在SDK的根目录下创建一个名为jtag-debug.sh的脚本文件。#!/bin/bash # 连接到远程的DebugServerIP和端口换成你实际的 target remote 172.16.31.141:3333 # 将调试符号文件elf加载到开发板的内存中 load ./output/d13x_demo88-nor_rt-thread_helloworld/images/d13x.elf # 指定本地用于读取符号的elf文件和load的是同一个 file ./output/d13x_demo88-nor_rt-thread_helloworld/images/d13x.elf记得把里面的IP地址、端口号以及elf文件的路径替换成你项目实际的信息。启动GDB并运行脚本在SDK根目录打开终端执行以下命令./toolchain/bin/riscv64-unknown-elf-gdb -x ./jtag-debug.sh这个命令会启动GDB并自动执行我们刚才写的脚本。连接成功如果一切顺利你会看到GDB启动信息然后脚本执行target remote连接成功接着load命令开始加载程序到板子内存中显示加载进度。当出现类似下面的信息时表示你已经成功进入GDB调试模式可以开始输入GDB命令如break main,continue,step等进行调试了。Loading section .text, size 0xa4780 lma 0x40000100 ... Loading section .rodata, size 0x843b8 lma 0x400a4880 ... Start address 0x0000000040000100, load size 1228312 Transfer rate: 107 KB/sec, 3988 bytes/write. (gdb)到这里整个基于衡山派开发板的GDB调试环境就搭建并连接成功了。无论是用图形化的Eclipse还是命令行的GDB核心都是通过T-HeadDebugServer这个桥梁。实际调试中如果连接失败多半要回头检查第4步的“按住CtrlC上电”操作是否成功以及DebugServer的IP和端口配置是否正确。这个流程我踩过几次坑按这个步骤来基本都能一次成功。
