GD32H759+RT-Thread工控环境搭建与点灯验证全指南

1. 为什么选 GD32H759 + RT-Thread 做工控入门？这颗芯片不是“国产替代”那么简单

GD32H759 这颗芯片刚发布时，我第一时间在立创商城下单了三片样品，不是因为它是兆易创新最新推出的高性能Cortex-M7内核MCU，而是因为它在工控场景里踩中了三个长期被忽略的痛点：实时性、外设一致性、开发链路平滑度。很多人看到“GD32H759”第一反应是“又一颗国产M7”，但真正用过GD32F4/F3系列的老工程师都知道，GD的外设寄存器映射逻辑和STM32高度兼容——不是表面兼容，是连GPIO复用功能切换时序、ADC采样保持时间、DMA请求触发边沿这些底层行为都几乎一致。这意味着什么？意味着你手头那套为STM32F407写的电机FOC控制算法，移植到GD32H759上，改的可能只是两行启动文件里的中断向量表地址，而不是重写整个外设驱动层。而RT-Thread作为国内最成熟的物联网实时操作系统，它的优势不在于“多线程调度有多炫”，而在于它对国产芯片的适配深度：从GD32全系列BSP包的更新频率（平均每月一次）、到SPI Flash自动识别机制、再到CAN FD协议栈的硬件加速支持，都是实打实由社区和官方团队在产线项目里反复打磨出来的。我去年带一个电梯门机控制项目，客户要求6个月内完成从原型到小批量交付，最后能按时交货，核心就是靠GD32H759+RT-Thread这套组合把底层驱动验证周期从传统方案的8周压缩到了11天。点灯实验看似简单，但它本质是验证整个工具链是否真正打通：从Keil MDK-ARM编译器能否正确识别GD32H759的Flash编程算法，到RT-Thread的finsh命令行能否通过串口正常打印，再到SysTick中断能否稳定触发线程调度——任何一个环节卡住，后续所有工控功能（比如CAN总线通信、EtherCAT从站实现、PWM死区时间配置）都会变成空中楼阁。所以这篇“第0篇”，不是教你怎么让LED闪烁，而是帮你建立一套可复用于后续所有GD32H759工控项目的标准化环境基线。关键词GD32H759、RT-Thread、环境搭建、点灯实验，每一个都不是孤立存在，它们共同构成了一条从芯片引脚到应用逻辑的完整信任链。

2. 环境搭建不是“下载安装包→点击下一步”，而是构建四层可信链

2.1 第一层：硬件平台与最小系统验证（绕不开的物理层）

GD32H759有三种封装：LQFP100、BGA176、BGA216，其中LQFP100最适合作为入门载体。但这里有个关键陷阱：官方开发板（如GD32H759-EVAL）的USB转串口芯片是CH340G，而很多国产USB转TTL模块用的是PL2303HXD——后者在Windows 11下驱动兼容性极差，经常出现“设备管理器里显示端口但实际无法通信”。我吃过这个亏，在调试UART打印时花了整整两天排查，最后发现是驱动问题而非代码错误。因此，硬件准备阶段必须做三件事：第一，确认开发板供电电压跳线设置为3.3V（GD32H759内核电压为1.2V，I/O电压为3.3V，接错会烧毁IO口）；第二，用万用表实测VDDA（模拟电源）和VSSA（模拟地）之间是否有0.1uF陶瓷电容并联（这是ADC精度保障的关键，缺了会导致AD值跳变±10LSB）；第三，检查BOOT0引脚是否通过10kΩ电阻下拉到GND（否则上电后会进入系统存储器启动模式，无法运行用户程序）。这些细节在数据手册第12章“电源管理”和第15章“复位与启动”里都有明确说明，但新手往往直接跳过。我建议用一块面包板搭个最小系统：只接VDD/VSS、VDDA/VSSA、BOOT0、NRST，再加一个100nF去耦电容到每个VDD引脚旁，这样能排除PCB设计缺陷带来的干扰。点灯实验的第一步，永远不是写代码，而是用示波器看NRST引脚上电瞬间是否有干净的复位脉冲（宽度需大于20us），这是后续所有软件行为可靠的前提。

2.2 第二层：Keil MDK-ARM 工具链配置（不是版本越高越好）

Keil MDK-ARM v5.38 是目前适配GD32H759最稳定的版本。注意，不是最新版v6.x，也不是老版本v5.25。原因很实在：v6.x引入了ARM Compiler 6（AC6），而GD32官方BSP包默认使用ARM Compiler 5（AC5），强行升级会导致startup_gd32h759.s里的汇编指令报错（比如AC6不支持某些旧语法）；v5.25则缺少对GD32H759 Flash编程算法的支持，烧录时会提示“Flash Algorithm not found”。安装时必须勾选“ARM Compiler 5”组件，同时在Pack Installer里搜索“GD32H759”并安装最新BSP包（截至2024年6月是GD32H759_DFP 3.0.0）。这里有个隐藏技巧：BSP包安装后，Keil会自动生成Device Support目录，但其中的system_gd32h759.c文件里，SystemCoreClock变量初始化值写的是180MHz，而GD32H759最高主频是480MHz——这个值必须手动改为480000000，否则后续所有基于SysTick的延时函数都会慢2.67倍。验证工具链是否正确，方法很简单：新建工程后，在Project → Options for Target → Device选项卡里，选择GD32H759VG，然后点击Manage Run-Time Environment，确保CMSIS、Device、RTOS三个分类下的所有组件都已勾选。此时如果点击Rebuild，应该能看到“0 Error(s), 0 Warning(s)”——但别急着高兴，这只是编译通过，还没验证链接是否正确。

2.3 第三层：RT-Thread 源码级集成（拒绝“一键生成”式移植）

RT-Thread官网提供的“在线生成器”确实能快速生成工程框架，但工控项目里，这种黑盒方式会埋下巨大隐患。比如生成器默认启用RT_USING_HEAP，即动态内存分配，但在GD32H759上，其内部SRAM只有512KB，若未精确配置heap_size，极易导致malloc失败却无日志提示。我的做法是：先从RT-Thread GitHub仓库克隆最新稳定版（v4.1.2），进入bsp/gd32/gd32h759-evb目录，这里存放着官方维护的BSP源码。重点看两个文件：board/board.c里的rt_hw_board_init()函数，它完成了时钟初始化（HSE=25MHz，PLL倍频至480MHz）、GPIO初始化（LED对应引脚配置为推挽输出）、以及串口初始化（USART0波特率115200）；另一个是drivers/gd32h759_gpio.c，它实现了RT-Thread标准GPIO驱动接口，比如rt_pin_write()底层调用的是GD32的gpio_bit_write()函数。移植时最关键的一步，是修改linker script（即gcc_ld_script.ld或keil_linker.sct）：GD32H759的Flash起始地址是0x08000000，大小2MB；SRAM1起始地址0x20000000，大小512KB；SRAM2起始地址0x20080000，大小128KB。必须确保.stack段分配在SRAM1，.data段放在SRAM1，而.heap段放在SRAM2——这样能避免主RAM被堆空间碎片化，影响实时任务响应。我曾在一个PLC项目里，因.heap和.stack都在同一块SRAM里，导致高优先级CAN接收线程被低优先级网络线程的malloc操作阻塞了3ms，最终造成总线超时。所以环境搭建阶段，一定要打开linker script，逐行核对内存布局。

2.4 第四层：调试与通信通道验证（没有串口日志的调试是盲人摸象）

GD32H759支持SWD和JTAG两种调试接口，但工控现场绝大多数用SWD（仅需SWCLK、SWDIO、GND三根线）。这里有个致命误区：很多人认为只要Keil能连接芯片就代表调试通了，其实不然。必须验证两个通道：一是SWD下载通道，二是UART0打印通道。验证SWD的方法是：在main函数开头加一句while(1);，然后全速运行，看Keil Debugger窗口是否能暂停在该行——如果不能，说明SWD时序参数没配对（在Options for Target → Debug → Settings里，SW Clock要设为4MHz，Protocol选SWD）。验证UART的方法更严格：不是用串口助手发“hello world”，而是用逻辑分析仪抓取TX引脚波形，确认起始位、8位数据、1位停止位、无校验位的帧结构是否符合115200波特率（每个bit宽度应为8.68us）。我见过太多案例，串口助手显示乱码，结果发现是晶振精度问题：开发板用的是±20ppm的普通晶振，而GD32H759的USART模块对时钟误差容忍度只有±2%，必须用±10ppm的高精度晶振才能保证长距离通信稳定。所以点灯实验前，务必用示波器测一下USART0_TX引脚空闲时的电平（应为高电平），再测发送单字节时的波形，这才是真正的“物理层握手成功”。

3. 点灯实验的七种实现方式与背后的技术决策逻辑

3.1 方式一：裸机轮询（最原始，但最能暴露硬件问题）

这是所有嵌入式入门必经之路，代码只有三行：

rcu_periph_clock_enable(RCU_GPIOB); gpio_mode_set(GPIOB, GPIO_PIN_0, GPIO_MODE_OUTPUT, GPIO_PUPD_NONE); gpio_output_bit_set(GPIOB, GPIO_PIN_0);

但背后有五个必须理解的细节：第一，RCU（Reset and Clock Unit）时钟使能是强制步骤，GD32H759所有外设都必须先开时钟，否则寄存器写无效；第二，GPIO_PIN_0对应PB0引脚，但开发板原理图上LED通常接在PB1或PE5，必须查原理图确认；第三，GPIO_PUPD_NONE表示不启用上下拉，但如果LED阳极接VCC，阴极通过限流电阻接地，则PB0输出低电平时LED才亮，此时要用gpio_output_bit_reset()；第四，这段代码必须放在SysTick初始化之前，否则如果SysTick中断里也操作同一GPIO，会产生竞态；第五，编译后生成的bin文件大小应小于4KB，否则说明链接脚本把代码放到了错误的Flash区域。我建议新手先用这种方式跑通，因为一旦LED不亮，问题一定出在硬件连接或时钟配置上，而不是操作系统层面。

3.2 方式二：裸机中断驱动（理解中断向量表的本质）

在GD32H759里，EXTI（External Interrupt）线0~15对应GPIO引脚0~15，但EXTI0只能由PA0/PB0/PC0等同名引脚触发，不能跨端口。所以如果LED接在PB0，想用外部中断控制，必须把PB0配置为输入，再接一个按键到PB0。关键代码：

exti_init(EXTI_0, EXTI_INTERRUPT, EXTI_TRIG_RISING); nvic_irq_enable(EXTI0_IRQn, 0, 0);

这里要注意：nvic_irq_enable的第二个参数是抢占优先级，GD32H759的NVIC有4位抢占优先级，0代表最高；第三个参数是子优先级，影响同级中断的响应顺序。如果后续要接入CAN中断（优先级设为1），就必须把EXTI0的抢占优先级设为0，否则按键中断会打断CAN接收。点灯实验用中断方式，价值在于验证NVIC配置是否正确——当按下按键时，用示波器测PB0电平，同时观察Keil的Debug → View → System Viewer → NVIC窗口，看EXTI0_IRQn状态是否从Pending变为Active，这是中断机制工作的铁证。

3.3 方式三：RT-Thread 线程+Finsh命令（验证OS基础功能）

创建一个LED控制线程：

static void led_thread_entry(void* parameter) { while(1) { rt_pin_write(LED_PIN, PIN_LOW); rt_thread_mdelay(500); rt_pin_write(LED_PIN, PIN_HIGH); rt_thread_mdelay(500); } } int main(void) { rt_thread_t tid = rt_thread_create("led", led_thread_entry, RT_NULL, 1024, 20, 10); if(tid != RT_NULL) rt_thread_startup(tid); return 0; }

这里的关键是参数：stack_size=1024字节，priority=20（数值越小优先级越高），tick=10（每10ms调度一次）。为什么设priority=20？因为RT-Thread默认idle线程优先级是31，timer线程是25，shell线程是20——如果LED线程也设为20，就会和shell线程同优先级，导致串口命令响应延迟。实测下来，priority=15最稳妥。另外，rt_thread_mdelay()底层调用的是rt_timer_control()，它依赖SysTick中断，所以必须确认board.c里SysTick_Config(SystemCoreClock / RT_TICK_PER_SECOND)是否执行成功（返回值为0）。验证OS是否真正在跑，方法是：在Finsh里输入list_thread，应该看到led、tshell、timer、idle四个线程，且led的stat列显示“SUSPENDED”或“READY”，而不是“CLOSED”。

3.4 方式四：RT-Thread 设备驱动模型（理解“一切皆文件”思想）

RT-Thread把LED抽象为字符设备：

static const struct rt_device_ops led_ops = { RT_NULL, RT_NULL, RT_NULL, RT_NULL, RT_NULL, RT_NULL, RT_NULL }; static struct rt_device led_device; int rt_hw_led_init(void) { rt_device_register(&led_device, "led0", RT_DEVICE_FLAG_RDWR); return 0; } INIT_BOARD_EXPORT(rt_hw_led_init);

然后在应用层用open("/dev/led0", O_RDWR)获取设备句柄。这种方式的价值在于：它强制你理解RT-Thread的设备注册机制——INIT_BOARD_EXPORT宏会把rt_hw_led_init函数地址放入.init_section段，系统启动时自动调用。如果忘记加这个宏，设备永远不会注册，open()会返回-1。我曾在一个客户项目里，因漏掉INIT_BOARD_EXPORT，导致Modbus从站设备无法被上位机识别，排查了三天才发现是设备注册链断裂。点灯实验用驱动模型，不是为了炫技，而是建立“设备即服务”的工控思维。

3.5 方式五：RT-Thread PWM输出（验证高级外设能力）

GD32H759的TIMER0~TIMER13都支持PWM输出，但只有TIMER0~TIMER3支持互补PWM（用于电机驱动）。点灯实验用PWM，是为了验证定时器高级功能：

timer_parameter_struct timer_initpara; timer_initpara.prescaler = 239; // 480MHz / (239+1) = 2MHz timer_initpara.countercfg.counter_period = 1999; // 2MHz / (1999+1) = 1kHz timer_initpara.countercfg.counterdirection = TIMER_COUNTER_UP; timer_init(TIMER0, &timer_initpara); timer_channel_output_config(TIMER0, TIMER_CH_0, &ch0_outpara); timer_channel_output_pulse_value_config(TIMER0, TIMER_CH_0, 999); // 占空比50% timer_primary_output_config(TIMER0, ENABLE); timer_enable(TIMER0);

这里prescaler=239是因为GD32H759的TIMER时钟源是APB2总线时钟（480MHz），必须分频到合理范围。如果设成0，计数器会溢出太快，LED看起来就是常亮。占空比计算公式是：pulse_value / counter_period。验证PWM是否生效，不能只看LED亮度，要用示波器测TIMER0_CH0引脚（通常是PA0），确认波形频率确实是1kHz，高电平时间500us——这才是硬件PWM的真实输出。

3.6 方式六：RT-Thread 软件定时器（理解时间片调度与精度边界）

创建一个软件定时器：

static rt_timer_t led_timer; static void led_timeout_handler(void* parameter) { static uint8_t state = 0; rt_pin_write(LED_PIN, state ? PIN_HIGH : PIN_LOW); state = !state; } led_timer = rt_timer_create("led", led_timeout_handler, RT_NULL, 500, RT_TIMER_FLAG_PERIODIC); if(led_timer != RT_NULL) rt_timer_start(led_timer);

软件定时器的精度取决于RT_TICK_PER_SECOND配置，默认是100（即10ms tick）。这意味着定时器最小分辨率是10ms，设500ms实际可能是490~510ms波动。如果需要精确500ms，必须用硬件定时器（如上面的TIMER0）。软件定时器的价值在于：它不占用额外硬件资源，适合做非实时性要求高的任务，比如看门狗喂狗、网络心跳包发送。验证它是否工作，方法是在led_timeout_handler里加一句rt_kprintf("timer fired\n");，然后用串口抓日志，看是否每500ms打印一次——但要注意，如果串口打印耗时超过10ms，会导致定时器回调堆积，必须用环形缓冲区异步处理。

3.7 方式七：RT-Thread 信号量同步（理解多线程协作机制）

创建两个线程，用信号量协调：

static rt_sem_t led_sem; static void led_on_thread(void* parameter) { while(1) { rt_sem_take(led_sem, RT_WAITING_FOREVER); rt_pin_write(LED_PIN, PIN_LOW); rt_thread_mdelay(100); } } static void led_off_thread(void* parameter) { while(1) { rt_pin_write(LED_PIN, PIN_HIGH); rt_thread_mdelay(100); rt_sem_release(led_sem); } } // 初始化时创建信号量：led_sem = rt_sem_create("led", 0, RT_IPC_FLAG_PRIO);

这个实验的价值在于：它暴露了RTOS最核心的同步机制。如果信号量初始值设为1，LED会常亮；设为0，LED会闪烁但周期不对。必须理解rt_sem_take()会阻塞当前线程直到信号量可用，而rt_sem_release()会唤醒等待者。用Keil的System Viewer看semaphore状态，能直观看到信号量计数器的变化过程。工控里，这种模式常用于“采集线程”和“处理线程”的解耦——比如ADC采集完一帧数据，释放信号量通知处理线程开始FFT运算。

4. 实操全流程：从零开始的12步环境搭建与点灯验证

4.1 步骤1：硬件准备清单与避坑清单

准备以下物料：

• GD32H759-EVAL开发板（官方型号，非山寨）
• J-Link EDU仿真器（固件版本必须≥V6.1，旧版不支持GD32H759）
• Micro-USB数据线（必须是带数据传输功能的，充电线不行）
• 万用表（测量VDD/VDDA电压）
• 逻辑分析仪（验证UART波形，推荐Saleae Logic 8）

避坑清单：

提示：开发板背面丝印“V3.0”的版本，其USB转串口电路使用CH340G，但部分批次CH340G的VCC引脚虚焊，导致串口无法识别。解决方法是用万用表测CH340G的VCC引脚对地电阻，正常应为几百欧姆，若为无穷大则需飞线补焊。 注意：GD32H759的BOOT1引脚在BGA封装里是复用的，LQFP100封装里是独立引脚，必须确认原理图上BOOT1是否悬空（默认高电平），否则可能误入系统存储器模式。

4.2 步骤2：Keil MDK-ARM 安装与激活

下载Keil MDK-ARM v5.38（官网提供免费试用版），安装时勾选：

• ARM Compiler 5（必须）
• Software Packs（必须，用于后续安装BSP）
• ULINK Pro Driver（如果用J-Link，此项可不选）

激活时，选择“Use the offline activation process”，生成Request Code后，用Keil官网的Offline Activation工具生成Activation Key。验证激活成功：打开Keil，Help → License Management，应显示“ARM Compiler 5: Unlimited”。

4.3 步骤3：安装GD32H759 BSP包

打开Pack Installer（Project → Manage → Pack Installer），在Search框输入“GD32H759”，找到“GigaDevice.GD32H759_DFP”，点击Install。安装完成后，在Project → Options for Target → Device选项卡里，Device下拉菜单应能选择“GD32H759VG”。

4.4 步骤4：创建RT-Thread工程模板

从RT-Thread官网下载rt-thread-v4.1.2.zip，解压后进入bsp/gd32/gd32h759-evb，复制整个文件夹到你的工作目录。用Keil打开project.uvprojx。此时编译会报错，因为缺少RT-Thread源码。解决方案：从rt-thread根目录复制src、include、components三个文件夹到bsp同级目录，然后在Keil里右键Project → Manage → Components，添加这些路径。

4.5 步骤5：修正系统时钟配置

打开board/Clock.c，找到SetSysClock()函数。原代码中PLL_M=25（HSE=25MHz），但开发板实际晶振是25MHz，所以无需修改。但PLL_N必须改为480（原为360），因为：

SYSCLK = HSE * PLL_N / PLL_M / PLL_P = 25 * 480 / 25 / 2 = 240MHz

等等，这里错了！GD32H759最高主频是480MHz，所以PLL_P应为1，PLL_N=480，计算得：

SYSCLK = 25 * 480 / 25 / 1 = 480MHz

修改后重新编译，确保无错误。

4.6 步骤6：配置Flash下载算法

在Project → Options for Target → Utilities → Settings，点击Add按钮，选择“GD32H759VG Flash”算法（在Keil安装目录的ARM\Flash\GigaDevice下）。验证方法：点击Load按钮，应能成功将程序烧录到Flash，并在Memory窗口看到0x08000000地址处有代码。

4.7 步骤7：配置串口打印通道

打开board/serial.c，确认USART0的GPIO配置：

rcu_periph_clock_enable(RCU_GPIOA); rcu_periph_clock_enable(RCU_USART0); gpio_init(GPIOA, GPIO_MODE_AF_PP, GPIO_OSPEED_50MHZ, GPIO_PIN_9); // TX gpio_init(GPIOA, GPIO_MODE_AF_PP, GPIO_OSPEED_50MHZ, GPIO_PIN_10); // RX

波特率设置为115200，无校验位。编译后，用XShell连接COMx，应能看到“RT-Thread starting...”启动日志。

4.8 步骤8：编写最简点灯代码

在applications/main.c里，删除原有代码，写入：

#include "rtthread.h" #include "drv_common.h" #define LED_PIN GET_PIN(B, 0) int main(void) { rt_pin_mode(LED_PIN, PIN_MODE_OUTPUT); while(1) { rt_pin_write(LED_PIN, PIN_HIGH); rt_thread_mdelay(500); rt_pin_write(LED_PIN, PIN_LOW); rt_thread_mdelay(500); } return RT_EOK; }

注意：GET_PIN(B,0)宏会根据BSP定义转换为具体引脚号，比硬编码更安全。

4.9 步骤9：编译与下载验证

点击Build按钮，应显示“0 Error(s), 0 Warning(s)”。点击Download，Keil底部Status栏显示“Programming Complete”。此时LED应开始闪烁。如果LED不亮，按顺序检查：万用表测PB0电压（应随代码变化），示波器测PB0波形（应有500ms高低电平交替）。

4.10 步骤10：Finsh命令行交互验证

在XShell里输入list_thread，应看到：

thread pri status sp stack size max used left tick error ------ --- ------- ---------- ---------- ------ ---------- --- tshell 20 ready 0x20001a00 0x00000400 25% 0x0000000a 00000000 led 15 ready 0x20001e00 0x00000400 12% 0x0000000a 00000000 timer 25 suspend 0x20002200 0x00000200 8% 0x0000000a 00000000 idle 31 ready 0x20002400 0x00000100 4% 0x0000000a 00000000

这证明RT-Thread内核、线程调度、定时器系统全部正常。

4.11 步骤11：添加PWM点灯验证

在main.c里添加：

#include "drv_timer.h" static struct rt_device_pwm *pwm_dev; int pwm_test_init(void) { pwm_dev = (struct rt_device_pwm *)rt_device_find("pwm0"); if(pwm_dev == RT_NULL) { rt_kprintf("pwm0 not found\n"); return -RT_ERROR; } rt_pwm_enable(pwm_dev, 0, 1000000); // 频率1MHz rt_pwm_set(pwm_dev, 0, 500000); // 占空比50% return RT_EOK; } INIT_APP_EXPORT(pwm_test_init);

编译下载后，用示波器测PA0引脚，应看到1MHz方波。此时LED会以人眼不可见的频率闪烁，但亮度恒定——这是PWM调光的基础。

4.12 步骤12：生成可复用的工程模板

将当前工程文件夹复制一份，重命名为“GD32H759_RTThread_Template_v1.0”。删除Objects和Listings文件夹（编译中间文件），保留所有源码和配置文件。这个模板将成为后续所有工控项目的起点，每次新建项目只需复制此文件夹，修改application代码即可。我建议在模板README.md里记录：Keil版本、RT-Thread版本、BSP版本、已验证的外设列表（如USART0、TIMER0、CAN0），这样团队协作时能避免环境差异。

5. 常见问题与排查技巧实录：那些文档里不会写的实战经验

5.1 问题1：Keil能连接J-Link，但无法下载程序，提示“Flash Download failed”

现象：Keil底部Status栏显示“Flash Download failed - Could not load file 'xxx.axf'”

排查思路：

1. 先确认J-Link固件版本：用J-Link Commander连接，输入“exec showversion”，若低于V6.1，必须升级；
2. 检查SWD接线：SWCLK、SWDIO、GND三根线是否接触良好，用万用表测SWDIO对地电阻，正常应为几kΩ，若为0Ω说明短路；
3. 查看Flash算法：在Utilities → Settings里，确认选中的是“GD32H759VG Flash”，而不是“GD32F450 Flash”；
4. 最隐蔽的原因：开发板上的RST引脚被其他电路拉低。用万用表测NRST对地电压，正常应为3.3V，若为0V，说明复位电路异常。

独家技巧：在Keil里，点击Debug → Start/Stop Debug Session，然后按Ctrl+Alt+K打开Debug Commands窗口，输入“reset”回车，再输入“load”加载axf文件。如果load成功，说明是复位时序问题，需在Options for Target → Debug → Settings → Reset中勾选“Under Reset”。

5.2 问题2：串口打印乱码，但波特率设置正确

现象：XShell显示“???”或完全空白

排查思路：

1. 用示波器测USART0_TX引脚，确认有波形输出，且bit宽度符合115200（8.68us）；
2. 如果波形正确但上位机乱码，检查XShell的串口设置：Data Bits=8，Stop Bits=1，Parity=None，Flow Control=None；
3. 如果波形也不对，检查board.c里USART0初始化代码，确认rcu_periph_clock_enable(RCU_USART0)是否执行；
4. 最容易被忽略的点：开发板USB转串口芯片的供电电压。CH340G需要3.3V供电，如果开发板VCC是5V，而CH340G的VCC引脚接到5V，会导致电平不匹配。

独家技巧：在main函数开头加一段测试代码：

for(int i=0; i<10; i++) { usart_data_transmit(USART0, 'A'+i); while(usart_flag_get(USART0, USART_FLAG_TC) == RESET); }

用逻辑分析仪抓这10个字节，如果波形正确，说明硬件没问题，问题出在RT-Thread的串口驱动层。

5.3 问题3：LED能点亮，但Finsh命令无响应

现象：串口能看到“RT-Thread starting...”，但输入任何命令都无回显

排查思路：

1. 在list_thread输出里，确认tshell线程状态是“ready”而非“suspend”；
2. 检查board.c里rt_hw_usart_init()函数，确认usart_interrupt_enable(USART0, USART_INT_RBNE)是否开启；
3. 用Keil的Debug → View → Serial Windows → USART0，看是否有数据接收；
4. 最可能的原因：Finsh命令缓冲区溢出。在rtconfig.h里，将FINSH_USR_CMD_SIZE从256改为512。

独家技巧：在Finsh里输入“ps”，如果返回“no task”，说明shell线程根本没起来。此时在rt_application_init()函数里，加一句rt_kprintf("shell init start\n");，看这条日志是否打印，就能定位是shell初始化前还是后出的问题。

5.4 问题4：RT-Thread线程创建失败，返回NULL

现象：rt_thread_create()返回RT_NULL

排查思路：

1. 检查rtconfig.h里RT_THREAD_STACK_SIZE_DEFAULT是否足够，默认是0x400（1024字节），对于简单线程够用，但若线程里调用printf，至少需要0x800；
2. 用rt_memheap_info()查看内存池状态，确认heap_size是否被设得太小；
3. 检查linker script，确认.heap段是否真的分配了空间，且起始地址在SRAM范围内；
4. 最隐蔽的bug：在rtconfig.h里，RT_USING_HEAP必须定义为1，否则所有动态内存分配都禁用。

独家技巧：在rt_thread_create()后加一句：

if(tid == RT_NULL) { rt_kprintf("thread create failed, heap size=%d\n", rt_system_heap_size()); }

这样能直接看到当前堆大小，比盲目猜更有针对性。

5.5 问题5：PWM输出频率不准，实测只有目标值的1/2

现象：代码设1MHz，示波器测得500kHz

排查思路：

1. 检查TIMER时钟源：GD32H759的TIMER0~TIMER3挂载在APB2总线（480MHz），TIMER4~TIMER13挂载在APB1总线（240MHz），必须确认使用的TIMER编号；
2. 查看TIMER初始化代码，确认prescaler值计算是否正确。例如，要得到1MHz，计数器时钟应为1MHz，所以prescaler = (APB2_CLK / 1MHz) - 1 = (480 - 1) = 479；
3. 检查counter_period设置，如果设为1000，实际频率是480MHz / 480 / 1000 = 1MHz，没错；
4. 最容易被忽略的点：GD32H759的TIMER有“重复计数器”模式，如果TIM_AUTORELOAD_PRELOAD_BIT被置位，会导致计数器在ARR寄存器更新后才生效，产生半个周期延迟。

独家技巧：用Keil的Debug → View → Memory Browser，直接读取TIMERx_CNT、TIMERx_PSC、TIMER