1. 为什么选GD32H759加RT-Thread这套组合拿到GD32H759这块板子的时候我第一反应是这性能放在工控场景里有点奢侈。Cortex-M7内核跑到600MHz带双精度浮点单元SRAM给到1MB以上还有TCM和Cache的配置空间——这个规格放在几年前是高端HMI或者边缘网关才用得上的。但这两年国产替代的节奏推着大家往前走很多原来跑STM32F4/H7的方案都在往国产平台迁移GD32H7系列就成了一个绕不开的选项。那为什么是RT-Thread而不是裸机或者FreeRTOS我自己的判断逻辑是这样的工控场景里你很难只做一件事。一个典型的设备可能要同时处理Modbus轮询、按键响应、屏幕刷新、数据记录、看门狗喂狗偶尔还要跑个简单的协议栈。裸机写前后台架构一开始还能撑住等到功能加到七八个模块那个while循环里的状态机就会变成一团乱麻。FreeRTOS当然也能用但RT-Thread在国内的生态更接地气——设备框架、FinSH控制台、软件包中心这些东西在你真正做产品的时候能省下大量重复造轮子的时间。这一篇是系列的第0篇目标很明确把环境搭起来把灯点起来。听起来简单但实际踩过的坑不少。GD32H759和STM32H7虽然引脚和寄存器有相似之处但时钟树配置、启动文件、链接脚本这些细节差异足够让一个老手折腾半天。我写这个系列的原则是每一步都给出可复现的操作每一个参数选择都说明理由不跳步不假设读者已经知道某些常识。提示这个系列面向的是有一定单片机基础、但第一次接触GD32H7系列或者RT-Thread的开发者。如果你连Keil或者IAR都没装过建议先补一下基础工具链的使用。2. 环境搭建前的整体规划与工具选型2.1 开发工具链的三种路线对比在动手之前先把工具链的选择想清楚。GD32H759的开发环境目前主流有三条路路线核心工具优点缺点适合人群Keil MDKKeil uVision5 GD32器件包生态成熟调试方便教程多商业授权费用高编辑器体验一般企业开发、习惯Keil的老手IAR EWARMIAR Embedded Workbench编译优化好调试器强授权贵上手曲线陡对代码体积和性能敏感的项目RT-Thread Studio基于Eclipse的IDE GCC免费与RT-Thread深度集成对GD32H7的支持需要手动配置个人开发者、RT-Thread用户我这次选的是RT-Thread Studio这条路。原因很直接这个系列的核心是RT-Thread用官方IDE能省去很多手动移植的工作。而且RT-Thread Studio内置了RT-Thread源码、软件包管理、FinSH终端对于后续要做的工控实战来说开发效率更高。当然如果你公司已经买了Keil的授权用Keil RT-Thread源码包的方式也完全可行只是配置步骤会多一些。2.2 需要提前准备的软硬件清单硬件方面GD32H759开发板一块我用的是官方EVAL板如果你的板子是第三方做的确认一下晶振频率和LED引脚调试器J-Link或者GD-Link。J-Link的兼容性更好RT-Thread Studio对它的支持也更完善USB转串口模块一个用来接FinSH控制台杜邦线若干5V电源或者USB供电软件方面RT-Thread Studio去官网下载最新版本安装时记得勾选GCC工具链GD32H7系列的器件支持包这个在RT-Thread Studio的SDK管理器里可以下载J-Link驱动或者GD-Link驱动根据你用的调试器来串口终端工具Putty或者SecureCRT都行我个人习惯用MobaXterm注意RT-Thread Studio的版本更新比较快不同版本对GD32H7的支持程度可能不一样。如果你在SDK管理器里找不到GD32H759的BSP可能需要手动从GitHub或者Gitee上拉取最新的BSP包。2.3 为什么先做点灯实验而不是直接上项目很多教程一上来就讲架构、讲线程调度、讲IPC机制我觉得那是反人性的。点灯实验的价值不在于点灯本身而在于它验证了整条工具链的连通性编译能过、下载能进、时钟跑对了、GPIO配置正确、RT-Thread的启动流程正常。这五个环节任何一个出问题灯都不会亮。所以点灯实验本质上是一个端到端的冒烟测试它跑通了后面的工作才有意义。而且GD32H759的时钟树比F1系列复杂得多PLL的配置涉及多个分频和倍频系数如果时钟没配对串口波特率会错延时函数会不准后面调什么都别扭。所以这一步必须稳。3. GD32H759的时钟与启动细节解析3.1 时钟树配置的关键参数计算GD32H759的最高主频是600MHz但这不是说你随便配个PLL就能跑上去的。它的时钟源选择、PLL分频系数、AHB/APB分频比都需要按照手册里的约束来算。我拿一个实际能跑的配置来演示假设外部晶振是25MHz大部分GD32H7开发板用的是这个频率目标系统时钟600MHz。GD32H7的PLL结构大致是输入时钟先经过一个预分频器PREDV得到PLL输入参考时钟然后经过倍频器PLLMF再经过分频器PLLP/PLLQ/PLLR具体计算过程25MHz晶振输入PREDV设为1得到25MHz的参考时钟PLLMF设为48得到25 × 48 1200MHz的VCO输出PLLP设为2得到600MHz的系统时钟AHB分频设为1AHB总线跑600MHzAPB1和APB2分频设为2外设总线跑300MHz这套参数在GD32H759上是能稳定跑的。但你要注意VCO的输出频率有范围限制一般在800MHz到1600MHz之间1200MHz是安全的。另外Flash的等待周期也要根据主频来设600MHz下需要设到最高的等待周期否则取指会出错。提示如果你用的是RT-Thread的BSP这些时钟配置通常已经在board.c或者system_gd32h7xx.c里写好了。但如果你要改主频一定要重新算一遍不能只改一个宏定义。3.2 启动文件与链接脚本的差异GD32H759的启动文件和STM32H7的启动文件长得很像但有几个关键差异中断向量表的偏移地址可能不同GD32H7系列的中断数量比STM32H7多一些启动文件里的堆栈大小设置RT-Thread有自己的要求堆至少要留够RT-Thread动态内存分配用链接脚本里的Flash和RAM地址范围GD32H759的Flash通常从0x08000000开始但RAM的分布要看具体型号我在第一次编译的时候遇到过一个链接错误提示RAM区域溢出。后来发现是链接脚本里只包含了DTCM没有把AXI SRAM算进去。GD32H759的RAM是分区域的DTCM、ITCM、AXI SRAM、SRAM1/2/3不同区域的访问速度和用途不一样。RT-Thread的堆通常放在AXI SRAM里因为容量大而中断向量表和关键代码可以放在ITCM里加速。3.3 RT-Thread的启动流程与GD32H7的适配RT-Thread在GD32H7上的启动流程大致是这样的复位后先执行启动文件的汇编代码设置堆栈指针初始化时钟跳到entry()函数这是RT-Thread的入口entry()里会调用rt_hw_board_init()这个函数在BSP的board.c里rt_hw_board_init()里做三件事初始化系统时钟、初始化串口、初始化堆内存然后创建main线程启动调度器这里最容易出问题的是第4步的堆内存初始化。RT-Thread用rt_system_heap_init()来指定堆的起始地址和大小。如果你指定的地址和链接脚本里的RAM区域对不上系统跑起来就会莫名其妙地死机。我的建议是在board.h里把RAM的布局用宏定义写清楚然后在链接脚本和board.c里都引用同一组宏避免手改漏改。4. 从零搭建RT-Thread Studio工程4.1 新建工程与BSP选择打开RT-Thread Studio新建RT-Thread项目。在BSP选择页面找到GD32系列然后选GD32H759对应的BSP。如果你找不到说明你的SDK版本太旧去SDK管理器里更新一下。新建完成后工程目录结构大概是这样的GD32H759_LED/ ├── applications/ │ └── main.c ├── board/ │ ├── board.c │ ├── board.h │ └── linker_scripts/ │ └── link.lds ├── libraries/ │ └── GD32H7xx_standard_peripheral/ ├── rt-thread/ │ ├── src/ │ ├── include/ │ └── components/ └── rtconfig.happlications/main.c是你写业务代码的地方board/下面是板级支持包rtconfig.h是RT-Thread的配置文件后面裁剪系统或者开软件包都在这里改。4.2 配置RT-Thread的关键选项在rtconfig.h里有几个选项需要确认RT_USING_HEAP必须打开否则不能用动态内存RT_USING_CONSOLE打开这样才能用FinSHRT_CONSOLE_DEVICE_NAME设成你实际用的串口比如uart0RT_USING_PIN打开点灯要用PIN设备框架RT_USING_DEVICE打开设备框架的基础如果你用的是RT-Thread Studio这些选项可以在图形化的配置界面里勾选不用手动改rtconfig.h。但知道它们对应哪些宏出问题的时候好排查。4.3 串口与FinSH的配置FinSH是RT-Thread的交互式终端通过串口和板子通信。配置步骤确认板子上的调试串口是哪个通常是UART0或者USART0在board.c里找到串口初始化的部分确认波特率设的是115200在rtconfig.h里确认RT_USING_FINSH是打开的编译下载后用串口终端连接波特率1152008N1按回车应该能看到msh /提示符如果看不到提示符先检查串口线是不是接对了TX和RX有没有交叉。然后检查波特率GD32H7的串口时钟源如果是APB总线300MHz的APB时钟下115200的波特率需要正确的分频系数这个在串口初始化代码里会自动算但如果你改了主频就要重新确认。注意有些开发板的串口0接了USB转串口芯片有些是引到排针上的。如果你用的是排针记得USB转串口模块的GND要和板子共地。5. 点灯实验的完整实现与代码解析5.1 硬件连接确认在写代码之前先确认LED接在哪个引脚上。我用的这块GD32H759 EVAL板LED1接在PA1LED2接在PA2低电平点亮。你的板子可能不一样查一下原理图把引脚号记下来。如果是自己画的板子注意LED的限流电阻一般220欧到1K欧都行太小了电流大太大了亮度不够。GD32H7的GPIO驱动能力比F1系列强但也不要直接短路到地。5.2 使用PIN设备框架点灯RT-Thread的PIN设备框架把GPIO操作抽象成了统一的API不用直接操作寄存器。点灯的代码大概长这样#include rtthread.h #include rtdevice.h #include board.h #define LED1_PIN GET_PIN(A, 1) #define LED2_PIN GET_PIN(A, 2) int main(void) { rt_pin_mode(LED1_PIN, PIN_MODE_OUTPUT); rt_pin_mode(LED2_PIN, PIN_MODE_OUTPUT); while (1) { rt_pin_write(LED1_PIN, PIN_LOW); rt_pin_write(LED2_PIN, PIN_HIGH); rt_thread_mdelay(500); rt_pin_write(LED1_PIN, PIN_HIGH); rt_pin_write(LED2_PIN, PIN_LOW); rt_thread_mdelay(500); } return RT_EOK; }GET_PIN(A, 1)这个宏把端口和引脚号拼成一个整数底层驱动会根据这个整数去操作对应的GPIO寄存器。rt_pin_mode()设置引脚为输出模式rt_pin_write()写电平rt_thread_mdelay()是RT-Thread的毫秒级延时会让出CPU给其他线程。5.3 直接操作寄存器的版本如果你想看看底层是怎么操作的或者你的RT-Thread配置里没开PIN设备框架可以直接用GD32的标准外设库#include gd32h7xx.h void led_init(void) { rcu_periph_clock_enable(RCU_GPIOA); gpio_mode_set(GPIOA, GPIO_MODE_OUTPUT, GPIO_PUPD_NONE, GPIO_PIN_1 | GPIO_PIN_2); gpio_output_options_set(GPIOA, GPIO_OTYPE_PP, GPIO_OSPEED_60MHZ, GPIO_PIN_1 | GPIO_PIN_2); gpio_bit_set(GPIOA, GPIO_PIN_1 | GPIO_PIN_2); } void led_toggle(void) { gpio_bit_toggle(GPIOA, GPIO_PIN_1 | GPIO_PIN_2); }这个版本需要手动开时钟、配模式、设速度。GPIO_OSPEED_60MHZ是输出速度点灯用最低速度就行但如果你后面要用SPI或者PWM速度就要调高。5.4 编译下载与现象验证代码写完后点编译。如果报错说找不到rtdevice.h检查一下rtconfig.h里RT_USING_DEVICE是不是打开了。如果报错说GET_PIN未定义检查RT_USING_PIN。编译通过后连接调试器点下载。下载完成后按复位键应该能看到两个LED交替闪烁周期1秒。同时串口终端上能看到RT-Thread的启动信息包括版本号、CPU架构、堆内存大小等。如果灯不亮按这个顺序排查用万用表量一下LED引脚的电平看有没有变化检查GPIO时钟有没有开检查引脚号对不对GET_PIN(A, 1)对应的是PA1不是PA0检查LED的极性有些板子是高电平点亮6. 常见问题与排查技巧实录6.1 编译报错与链接错误速查错误现象可能原因解决方法undefined reference to rt_pin_modePIN设备框架没开在rtconfig.h里打开RT_USING_PINregion RAM overflowed链接脚本RAM区域不够检查堆栈大小把堆放到AXI SRAMcannot open linker script file链接脚本路径不对检查工程设置里的链接脚本路径No such file: gd32h7xx.h器件包没装在SDK管理器里安装GD32H7支持包6.2 下载失败与调试器连接问题J-Link连不上GD32H759最常见的原因是调试接口被禁用了。GD32H7默认是开SWD接口的但如果你之前烧过程序把SWD引脚复用成了GPIO就会连不上。解决办法是按住复位键点下载然后松开复位键让芯片在复位状态下被调试器接管。还有一种情况是调试器供电不足。GD32H759的功耗比F1系列大如果只用调试器的3.3V供电可能带不动。建议板子单独供电调试器的GND和板子共地就行。6.3 串口乱码与FinSH无响应串口乱码九成是波特率不对。GD32H7的串口时钟源如果是APB主频改了之后波特率分频系数要重算。RT-Thread的串口驱动里通常有自动计算但如果你用的是自己写的驱动就要手动确认。FinSH无响应但串口有输出可能是FinSH线程的优先级太低被其他线程抢占了。检查一下RT_USING_FINSH的线程优先级配置默认是比main线程高的但如果你改过就要确认一下。提示如果FinSH能显示提示符但输入没反应检查串口终端的本地回显是不是关了。有些终端工具默认不回显你输入字符看不到但实际上已经发出去了。6.4 点灯实验中的几个坑第一个坑是rt_thread_mdelay()在调度器启动前不能用。如果你在main()函数里、调度器还没启动的时候调用它系统会卡死。点灯代码放在main线程里是没问题的因为main线程本身就是调度器启动后创建的。第二个坑是GPIO的时钟。GD32H7的GPIO时钟使能和F1系列不一样F1是RCC_APB2ENRH7是RCU_GPIOA这种宏。如果你从F1的代码抄过来编译能过但灯不亮就是时钟没开对。第三个坑是LED的闪烁频率。如果你用rt_thread_mdelay(500)实际闪烁周期是1秒因为亮500ms灭500ms。如果你想让它闪得快一点改成100或者200但不要低于50否则人眼看起来就是常亮。7. 工程模板的整理与后续扩展7.1 把配置固化成模板环境搭好之后我习惯把整个工程目录复制一份改名叫GD32H759_RTT_Template然后把applications/main.c里的点灯代码清掉只留一个空的main函数。这样下次开新项目直接复制这个模板改改工程名就能用不用每次都重新配时钟、配串口、配FinSH。模板里要保留的东西board/目录下的所有板级配置rtconfig.h里已经调好的选项链接脚本调试配置J-Link的下载算法、复位方式7.2 下一步可以做的实验点灯跑通之后下一步我建议做串口收发实验。用FinSH的msh命令加上自定义的msh命令把串口的中断收发跑通。这个实验能验证中断向量表、NVIC配置、串口驱动是否正常。再往后可以做定时器实验、PWM实验、ADC采样实验。这些外设的驱动在RT-Thread里都有现成的设备框架用起来比裸机方便很多。但前提是时钟和中断要配对所以第0篇的基础一定要打牢。7.3 关于GD32H7系列的选型建议如果你正在选型GD32H759适合的场景是需要较高算力、有显示或者网络需求、对成本有一定敏感度的工控设备。它的主要竞争对手是STM32H7系列优势在于供货和价格劣势在于生态和文档的完善程度。RT-Thread对GD32的支持在逐步完善但一些小众外设的驱动可能还需要自己写。我个人在实际操作中的体会是GD32H7的寄存器操作和STM32H7有八成相似但剩下那两成差异往往是最耗时的。所以从STM32迁移过来的时候不要假设应该一样每个外设都对着GD32的手册确认一遍反而更快。最后再分享一个小技巧RT-Thread Studio的工程文件里.cproject和.project这两个文件记录了工程的配置信息。如果你要把工程分享给别人或者从别人的工程复制过来这两个文件最好一起带上否则对方打开后可能找不到头文件路径或者链接脚本。如果只想要源码那就把applications/、board/、rtconfig.h这三个部分拷走在新工程里替换掉对应的文件这样最干净。
GD32H759+RT-Thread实战：从零搭建环境到点灯
1. 为什么选GD32H759加RT-Thread这套组合拿到GD32H759这块板子的时候我第一反应是这性能放在工控场景里有点奢侈。Cortex-M7内核跑到600MHz带双精度浮点单元SRAM给到1MB以上还有TCM和Cache的配置空间——这个规格放在几年前是高端HMI或者边缘网关才用得上的。但这两年国产替代的节奏推着大家往前走很多原来跑STM32F4/H7的方案都在往国产平台迁移GD32H7系列就成了一个绕不开的选项。那为什么是RT-Thread而不是裸机或者FreeRTOS我自己的判断逻辑是这样的工控场景里你很难只做一件事。一个典型的设备可能要同时处理Modbus轮询、按键响应、屏幕刷新、数据记录、看门狗喂狗偶尔还要跑个简单的协议栈。裸机写前后台架构一开始还能撑住等到功能加到七八个模块那个while循环里的状态机就会变成一团乱麻。FreeRTOS当然也能用但RT-Thread在国内的生态更接地气——设备框架、FinSH控制台、软件包中心这些东西在你真正做产品的时候能省下大量重复造轮子的时间。这一篇是系列的第0篇目标很明确把环境搭起来把灯点起来。听起来简单但实际踩过的坑不少。GD32H759和STM32H7虽然引脚和寄存器有相似之处但时钟树配置、启动文件、链接脚本这些细节差异足够让一个老手折腾半天。我写这个系列的原则是每一步都给出可复现的操作每一个参数选择都说明理由不跳步不假设读者已经知道某些常识。提示这个系列面向的是有一定单片机基础、但第一次接触GD32H7系列或者RT-Thread的开发者。如果你连Keil或者IAR都没装过建议先补一下基础工具链的使用。2. 环境搭建前的整体规划与工具选型2.1 开发工具链的三种路线对比在动手之前先把工具链的选择想清楚。GD32H759的开发环境目前主流有三条路路线核心工具优点缺点适合人群Keil MDKKeil uVision5 GD32器件包生态成熟调试方便教程多商业授权费用高编辑器体验一般企业开发、习惯Keil的老手IAR EWARMIAR Embedded Workbench编译优化好调试器强授权贵上手曲线陡对代码体积和性能敏感的项目RT-Thread Studio基于Eclipse的IDE GCC免费与RT-Thread深度集成对GD32H7的支持需要手动配置个人开发者、RT-Thread用户我这次选的是RT-Thread Studio这条路。原因很直接这个系列的核心是RT-Thread用官方IDE能省去很多手动移植的工作。而且RT-Thread Studio内置了RT-Thread源码、软件包管理、FinSH终端对于后续要做的工控实战来说开发效率更高。当然如果你公司已经买了Keil的授权用Keil RT-Thread源码包的方式也完全可行只是配置步骤会多一些。2.2 需要提前准备的软硬件清单硬件方面GD32H759开发板一块我用的是官方EVAL板如果你的板子是第三方做的确认一下晶振频率和LED引脚调试器J-Link或者GD-Link。J-Link的兼容性更好RT-Thread Studio对它的支持也更完善USB转串口模块一个用来接FinSH控制台杜邦线若干5V电源或者USB供电软件方面RT-Thread Studio去官网下载最新版本安装时记得勾选GCC工具链GD32H7系列的器件支持包这个在RT-Thread Studio的SDK管理器里可以下载J-Link驱动或者GD-Link驱动根据你用的调试器来串口终端工具Putty或者SecureCRT都行我个人习惯用MobaXterm注意RT-Thread Studio的版本更新比较快不同版本对GD32H7的支持程度可能不一样。如果你在SDK管理器里找不到GD32H759的BSP可能需要手动从GitHub或者Gitee上拉取最新的BSP包。2.3 为什么先做点灯实验而不是直接上项目很多教程一上来就讲架构、讲线程调度、讲IPC机制我觉得那是反人性的。点灯实验的价值不在于点灯本身而在于它验证了整条工具链的连通性编译能过、下载能进、时钟跑对了、GPIO配置正确、RT-Thread的启动流程正常。这五个环节任何一个出问题灯都不会亮。所以点灯实验本质上是一个端到端的冒烟测试它跑通了后面的工作才有意义。而且GD32H759的时钟树比F1系列复杂得多PLL的配置涉及多个分频和倍频系数如果时钟没配对串口波特率会错延时函数会不准后面调什么都别扭。所以这一步必须稳。3. GD32H759的时钟与启动细节解析3.1 时钟树配置的关键参数计算GD32H759的最高主频是600MHz但这不是说你随便配个PLL就能跑上去的。它的时钟源选择、PLL分频系数、AHB/APB分频比都需要按照手册里的约束来算。我拿一个实际能跑的配置来演示假设外部晶振是25MHz大部分GD32H7开发板用的是这个频率目标系统时钟600MHz。GD32H7的PLL结构大致是输入时钟先经过一个预分频器PREDV得到PLL输入参考时钟然后经过倍频器PLLMF再经过分频器PLLP/PLLQ/PLLR具体计算过程25MHz晶振输入PREDV设为1得到25MHz的参考时钟PLLMF设为48得到25 × 48 1200MHz的VCO输出PLLP设为2得到600MHz的系统时钟AHB分频设为1AHB总线跑600MHzAPB1和APB2分频设为2外设总线跑300MHz这套参数在GD32H759上是能稳定跑的。但你要注意VCO的输出频率有范围限制一般在800MHz到1600MHz之间1200MHz是安全的。另外Flash的等待周期也要根据主频来设600MHz下需要设到最高的等待周期否则取指会出错。提示如果你用的是RT-Thread的BSP这些时钟配置通常已经在board.c或者system_gd32h7xx.c里写好了。但如果你要改主频一定要重新算一遍不能只改一个宏定义。3.2 启动文件与链接脚本的差异GD32H759的启动文件和STM32H7的启动文件长得很像但有几个关键差异中断向量表的偏移地址可能不同GD32H7系列的中断数量比STM32H7多一些启动文件里的堆栈大小设置RT-Thread有自己的要求堆至少要留够RT-Thread动态内存分配用链接脚本里的Flash和RAM地址范围GD32H759的Flash通常从0x08000000开始但RAM的分布要看具体型号我在第一次编译的时候遇到过一个链接错误提示RAM区域溢出。后来发现是链接脚本里只包含了DTCM没有把AXI SRAM算进去。GD32H759的RAM是分区域的DTCM、ITCM、AXI SRAM、SRAM1/2/3不同区域的访问速度和用途不一样。RT-Thread的堆通常放在AXI SRAM里因为容量大而中断向量表和关键代码可以放在ITCM里加速。3.3 RT-Thread的启动流程与GD32H7的适配RT-Thread在GD32H7上的启动流程大致是这样的复位后先执行启动文件的汇编代码设置堆栈指针初始化时钟跳到entry()函数这是RT-Thread的入口entry()里会调用rt_hw_board_init()这个函数在BSP的board.c里rt_hw_board_init()里做三件事初始化系统时钟、初始化串口、初始化堆内存然后创建main线程启动调度器这里最容易出问题的是第4步的堆内存初始化。RT-Thread用rt_system_heap_init()来指定堆的起始地址和大小。如果你指定的地址和链接脚本里的RAM区域对不上系统跑起来就会莫名其妙地死机。我的建议是在board.h里把RAM的布局用宏定义写清楚然后在链接脚本和board.c里都引用同一组宏避免手改漏改。4. 从零搭建RT-Thread Studio工程4.1 新建工程与BSP选择打开RT-Thread Studio新建RT-Thread项目。在BSP选择页面找到GD32系列然后选GD32H759对应的BSP。如果你找不到说明你的SDK版本太旧去SDK管理器里更新一下。新建完成后工程目录结构大概是这样的GD32H759_LED/ ├── applications/ │ └── main.c ├── board/ │ ├── board.c │ ├── board.h │ └── linker_scripts/ │ └── link.lds ├── libraries/ │ └── GD32H7xx_standard_peripheral/ ├── rt-thread/ │ ├── src/ │ ├── include/ │ └── components/ └── rtconfig.happlications/main.c是你写业务代码的地方board/下面是板级支持包rtconfig.h是RT-Thread的配置文件后面裁剪系统或者开软件包都在这里改。4.2 配置RT-Thread的关键选项在rtconfig.h里有几个选项需要确认RT_USING_HEAP必须打开否则不能用动态内存RT_USING_CONSOLE打开这样才能用FinSHRT_CONSOLE_DEVICE_NAME设成你实际用的串口比如uart0RT_USING_PIN打开点灯要用PIN设备框架RT_USING_DEVICE打开设备框架的基础如果你用的是RT-Thread Studio这些选项可以在图形化的配置界面里勾选不用手动改rtconfig.h。但知道它们对应哪些宏出问题的时候好排查。4.3 串口与FinSH的配置FinSH是RT-Thread的交互式终端通过串口和板子通信。配置步骤确认板子上的调试串口是哪个通常是UART0或者USART0在board.c里找到串口初始化的部分确认波特率设的是115200在rtconfig.h里确认RT_USING_FINSH是打开的编译下载后用串口终端连接波特率1152008N1按回车应该能看到msh /提示符如果看不到提示符先检查串口线是不是接对了TX和RX有没有交叉。然后检查波特率GD32H7的串口时钟源如果是APB总线300MHz的APB时钟下115200的波特率需要正确的分频系数这个在串口初始化代码里会自动算但如果你改了主频就要重新确认。注意有些开发板的串口0接了USB转串口芯片有些是引到排针上的。如果你用的是排针记得USB转串口模块的GND要和板子共地。5. 点灯实验的完整实现与代码解析5.1 硬件连接确认在写代码之前先确认LED接在哪个引脚上。我用的这块GD32H759 EVAL板LED1接在PA1LED2接在PA2低电平点亮。你的板子可能不一样查一下原理图把引脚号记下来。如果是自己画的板子注意LED的限流电阻一般220欧到1K欧都行太小了电流大太大了亮度不够。GD32H7的GPIO驱动能力比F1系列强但也不要直接短路到地。5.2 使用PIN设备框架点灯RT-Thread的PIN设备框架把GPIO操作抽象成了统一的API不用直接操作寄存器。点灯的代码大概长这样#include rtthread.h #include rtdevice.h #include board.h #define LED1_PIN GET_PIN(A, 1) #define LED2_PIN GET_PIN(A, 2) int main(void) { rt_pin_mode(LED1_PIN, PIN_MODE_OUTPUT); rt_pin_mode(LED2_PIN, PIN_MODE_OUTPUT); while (1) { rt_pin_write(LED1_PIN, PIN_LOW); rt_pin_write(LED2_PIN, PIN_HIGH); rt_thread_mdelay(500); rt_pin_write(LED1_PIN, PIN_HIGH); rt_pin_write(LED2_PIN, PIN_LOW); rt_thread_mdelay(500); } return RT_EOK; }GET_PIN(A, 1)这个宏把端口和引脚号拼成一个整数底层驱动会根据这个整数去操作对应的GPIO寄存器。rt_pin_mode()设置引脚为输出模式rt_pin_write()写电平rt_thread_mdelay()是RT-Thread的毫秒级延时会让出CPU给其他线程。5.3 直接操作寄存器的版本如果你想看看底层是怎么操作的或者你的RT-Thread配置里没开PIN设备框架可以直接用GD32的标准外设库#include gd32h7xx.h void led_init(void) { rcu_periph_clock_enable(RCU_GPIOA); gpio_mode_set(GPIOA, GPIO_MODE_OUTPUT, GPIO_PUPD_NONE, GPIO_PIN_1 | GPIO_PIN_2); gpio_output_options_set(GPIOA, GPIO_OTYPE_PP, GPIO_OSPEED_60MHZ, GPIO_PIN_1 | GPIO_PIN_2); gpio_bit_set(GPIOA, GPIO_PIN_1 | GPIO_PIN_2); } void led_toggle(void) { gpio_bit_toggle(GPIOA, GPIO_PIN_1 | GPIO_PIN_2); }这个版本需要手动开时钟、配模式、设速度。GPIO_OSPEED_60MHZ是输出速度点灯用最低速度就行但如果你后面要用SPI或者PWM速度就要调高。5.4 编译下载与现象验证代码写完后点编译。如果报错说找不到rtdevice.h检查一下rtconfig.h里RT_USING_DEVICE是不是打开了。如果报错说GET_PIN未定义检查RT_USING_PIN。编译通过后连接调试器点下载。下载完成后按复位键应该能看到两个LED交替闪烁周期1秒。同时串口终端上能看到RT-Thread的启动信息包括版本号、CPU架构、堆内存大小等。如果灯不亮按这个顺序排查用万用表量一下LED引脚的电平看有没有变化检查GPIO时钟有没有开检查引脚号对不对GET_PIN(A, 1)对应的是PA1不是PA0检查LED的极性有些板子是高电平点亮6. 常见问题与排查技巧实录6.1 编译报错与链接错误速查错误现象可能原因解决方法undefined reference to rt_pin_modePIN设备框架没开在rtconfig.h里打开RT_USING_PINregion RAM overflowed链接脚本RAM区域不够检查堆栈大小把堆放到AXI SRAMcannot open linker script file链接脚本路径不对检查工程设置里的链接脚本路径No such file: gd32h7xx.h器件包没装在SDK管理器里安装GD32H7支持包6.2 下载失败与调试器连接问题J-Link连不上GD32H759最常见的原因是调试接口被禁用了。GD32H7默认是开SWD接口的但如果你之前烧过程序把SWD引脚复用成了GPIO就会连不上。解决办法是按住复位键点下载然后松开复位键让芯片在复位状态下被调试器接管。还有一种情况是调试器供电不足。GD32H759的功耗比F1系列大如果只用调试器的3.3V供电可能带不动。建议板子单独供电调试器的GND和板子共地就行。6.3 串口乱码与FinSH无响应串口乱码九成是波特率不对。GD32H7的串口时钟源如果是APB主频改了之后波特率分频系数要重算。RT-Thread的串口驱动里通常有自动计算但如果你用的是自己写的驱动就要手动确认。FinSH无响应但串口有输出可能是FinSH线程的优先级太低被其他线程抢占了。检查一下RT_USING_FINSH的线程优先级配置默认是比main线程高的但如果你改过就要确认一下。提示如果FinSH能显示提示符但输入没反应检查串口终端的本地回显是不是关了。有些终端工具默认不回显你输入字符看不到但实际上已经发出去了。6.4 点灯实验中的几个坑第一个坑是rt_thread_mdelay()在调度器启动前不能用。如果你在main()函数里、调度器还没启动的时候调用它系统会卡死。点灯代码放在main线程里是没问题的因为main线程本身就是调度器启动后创建的。第二个坑是GPIO的时钟。GD32H7的GPIO时钟使能和F1系列不一样F1是RCC_APB2ENRH7是RCU_GPIOA这种宏。如果你从F1的代码抄过来编译能过但灯不亮就是时钟没开对。第三个坑是LED的闪烁频率。如果你用rt_thread_mdelay(500)实际闪烁周期是1秒因为亮500ms灭500ms。如果你想让它闪得快一点改成100或者200但不要低于50否则人眼看起来就是常亮。7. 工程模板的整理与后续扩展7.1 把配置固化成模板环境搭好之后我习惯把整个工程目录复制一份改名叫GD32H759_RTT_Template然后把applications/main.c里的点灯代码清掉只留一个空的main函数。这样下次开新项目直接复制这个模板改改工程名就能用不用每次都重新配时钟、配串口、配FinSH。模板里要保留的东西board/目录下的所有板级配置rtconfig.h里已经调好的选项链接脚本调试配置J-Link的下载算法、复位方式7.2 下一步可以做的实验点灯跑通之后下一步我建议做串口收发实验。用FinSH的msh命令加上自定义的msh命令把串口的中断收发跑通。这个实验能验证中断向量表、NVIC配置、串口驱动是否正常。再往后可以做定时器实验、PWM实验、ADC采样实验。这些外设的驱动在RT-Thread里都有现成的设备框架用起来比裸机方便很多。但前提是时钟和中断要配对所以第0篇的基础一定要打牢。7.3 关于GD32H7系列的选型建议如果你正在选型GD32H759适合的场景是需要较高算力、有显示或者网络需求、对成本有一定敏感度的工控设备。它的主要竞争对手是STM32H7系列优势在于供货和价格劣势在于生态和文档的完善程度。RT-Thread对GD32的支持在逐步完善但一些小众外设的驱动可能还需要自己写。我个人在实际操作中的体会是GD32H7的寄存器操作和STM32H7有八成相似但剩下那两成差异往往是最耗时的。所以从STM32迁移过来的时候不要假设应该一样每个外设都对着GD32的手册确认一遍反而更快。最后再分享一个小技巧RT-Thread Studio的工程文件里.cproject和.project这两个文件记录了工程的配置信息。如果你要把工程分享给别人或者从别人的工程复制过来这两个文件最好一起带上否则对方打开后可能找不到头文件路径或者链接脚本。如果只想要源码那就把applications/、board/、rtconfig.h这三个部分拷走在新工程里替换掉对应的文件这样最干净。
代码包深度解析与实践指南)
