GD32E10x标准外设库例程工程搭建与外设调试避坑

简介：这份GD32E10x系列官方例程面向使用ARM Cortex-M3内核单片机的嵌入式开发者、高校学生与硬件工程师，提供从系统时钟配置、外设初始化到中断处理的完整参考代码，可用于工业控制、消费电子与通信设备等场景的快速验证与开发板调试。压缩包共935个文件，约11.16MB，以288个h头文件、261个c源文件为核心，并配有Keil与IAR工程文件、启动汇编、Makefile、PDF文档、HEX烧录文件及少量工具程序，目录按功能模块组织，便于检索、对照与移植。已有880人学习。例程覆盖GPIO、SPI、I2C、UART、ADC、DAC、定时器、CAN、USB主机及低功耗模式等，读者可据此理解外设驱动、中断服务与工程配置，也可直接编译调试、烧录验证，对初次接触GD32系列的读者较为友好，适合作为入门学习与项目原型的参考，从而缩短开发周期并提升嵌入式系统开发能力。

1. 拆开 GD32E10x 官方例程包：先搞清楚它能省掉哪部分重复劳动

GD32E10x 系列官方例程包，压缩包里是一整套基于 Cortex-M4 内核的标准外设库，外加按外设切开的工程 demo：GPIO、USART、TIMER、ADC、DMA、EXMC、USB，每个都能单独编译下载。第一次接触 ARM 单片机的人容易把它当教学课件，挨个点开跑一遍，灯闪了、串口吐字了就认为任务完成；但真正值钱的部分是gd32e10x_xxx.c那一堆寄存器封装，它把 120MHz 主频下的时钟树、引脚复用、DMA 请求映射这些容易配错的细节固化成了函数调用。适合的场景很明确：新板子刚回来，需要逐项点亮验证硬件；或者从同类 M4 平台迁移过来，手上没有图形化配置工具、只想用裸机标准库把工程搭起来。下面按照“目录怎么取舍 → 外设怎么拆 → 坑在哪”的顺序拆。

2. 工程骨架怎么搭：从 Template 到可量产的目录分层

例程包解压后第一眼看目录会有点散，Firmware、Template、Examples、Utilities并列摆着，各自还带若干子目录。这里先定一个原则：固件库是整个工程的底盘，必须原样进入版本管理；Example 里的工程文件是参考，只抄配置片段，不整个搬。很多项目后期难以维护，原因不在代码水平，而是把十几个 Example 的工程文件揉在一起，改一个宏定义时要翻五个地方。

2.1 固件库里哪几个目录必须进版本管理

Firmware下面通常分两块：CMSIS和GD32E10x_standard_peripheral。前者是内核头文件、启动汇编、系统时钟初始化文件；后者是每个外设一个.c加一个.h，比如gd32e10x_gpio.c、gd32e10x_usart.c、gd32e10x_rcu.c。

裁剪Src目录是最省事的一步：一个只做串口采集的板子，gd32e10x_can.c、gd32e10x_exmc.c、gd32e10x_usb*.c全可以从工程里移除，编译时间能砍掉一大截，也减少后期误调用的可能。反过来，gd32e10x_rcu.c和gd32e10x_misc.c（NVIC 配置）绝对不能少。

2.2 用 Template 建骨架的六步操作

我一般按固定六步做，做完就能得到一个干净的空工程：

1. 建目录：app/（业务代码）、bsp/（板级驱动）、lib/（固件库）、project/（工程文件）。
2. 把Firmware整个拷进lib/，删掉其他编译器用不到的启动文件。
3. 工程里加入启动文件、system_gd32e10x.c、用到的外设.c、main.c。
4. 加全局宏GD32E10X，这个宏决定了头文件里寄存器基地址走哪一套分支，漏掉会报一堆未定义。
5. 加头文件搜索路径：lib/CMSIS、lib/GD32E10x_standard_peripheral/Inc、bsp、app。
6. 打开system_gd32e10x.c，确认时钟选择宏只留一个。

第 6 步单独说，因为这里最容易出问题。文件顶部通常是一组被注释掉的选择项，形如__SYSTEM_CLOCK_IRC8M、__SYSTEM_CLOCK_HXTAL、__SYSTEM_CLOCK_120M_PLL_HXTAL之类，取消注释优先级最高的那个才会生效：

/* system_gd32e10x.c 顶部：只保留一个定义，其余全部注释 */ #define __SYSTEM_CLOCK_120M_PLL_HXTAL /* #define __SYSTEM_CLOCK_120M_PLL_IRC8M_DIV2 */

这段代码的作用是在SystemInit()里选择 PLL 的输入源和倍频系数。120M_PLL_HXTAL表示外部晶振经 PLL 倍频到 120MHz，是绝大多数板子的目标配置；带IRC8M的那几个选项用内部 8MHz RC 做源，精度差但不需要外部晶振，适合先验证芯片有没有活。参数上唯一要确认的是外部晶振频率，库里默认按 8MHz 算倍频，如果板子焊的是 12MHz 或 25MHz，PLL 系数就得跟着改，否则系统跑在一个谁也不知道的频率上，串口波特率会跟着一起错。

2.3 系统时钟从 HXTAL 到 120MHz 的逐段核对

搭完骨架不要急着写业务，先用两行代码把实际频率读回来。库里有现成的查询函数，返回值单位是 Hz：

#include "gd32e10x.h" #include "gd32e10x_rcu.h" int main(void) { /* 读回实际系统时钟，别相信头文件里的注释 */ uint32_t sysclk = rcu_clock_freq_get(CK_SYS); uint32_t ahb = rcu_clock_freq_get(CK_AHB); uint32_t apb2 = rcu_clock_freq_get(CK_APB2); /* 预期：sysclk = 120000000, ahb 同频, apb2 视分频配置 */ while(1) { /* 打断点看这三个值，或者从串口打印出来 */ } }

rcu_clock_freq_get的入参是时钟域枚举，CK_SYS是系统时钟，CK_AHB是 AHB 总线，CK_APB1、CK_APB2是两条外设总线。这三个值必须符合预期，后面的串口、定时器、ADC 才有讨论意义——波特率算错、PWM 频率差几倍、ADC 采样率不对，十有八九根子在这里。

想更直观一点，把系统时钟从时钟输出脚上引出来，接示波器直接量：

void ckout_init(void) { rcu_periph_clock_enable(RCU_GPIOA); /* PA8 复用为时钟输出，源选 CK_SYS，不分频 */ gpio_init(GPIOA, GPIO_MODE_AF_PP, GPIO_OSPEED_50MHZ, GPIO_PIN_8); rcu_ckout0_config(RCU_CKOUT0SRC_CKSYS, RCU_CKOUT0_DIV1); }

第一个参数是输出源，除了CK_SYS还能选CK_IRC8M、CK_HXTAL、CK_PLLCK等，第二个参数是分频系数。示波器量到 120MHz 方波，说明整条 PLL 链路是通的；量到 8MHz，说明外部晶振没起振，系统悄悄退回内部 RC 了——这个现象在避坑那一章还会再提一次，它是新手最容易误判成“库有问题”的情形。

3. GPIO 与串口链路：把例程拆成自己的驱动层

骨架搭好之后，第一件要落地的事是把 GPIO 和串口跑通，因为后面所有调试手段都依赖串口打印。例程里的GPIO和USART两个 demo 各自独立，实际项目里它们要合成一个bsp_uart.c，同时把引脚初始化、中断、收发缓冲一起收进去。

3.1 gpio_init 的四个参数与输出速度的真实影响

标准外设库的 GPIO 初始化和很多人熟悉的写法不一样，一个函数配完端口、模式、速度、引脚四个维度：

void bsp_led_init(void) { /* 开 GPIOB 的时钟，注意是 RCU_GPIOB，不是 RCU_GPIOA */ rcu_periph_clock_enable(RCU_GPIOB); /* 推挽输出，速度档 2MHz，引脚 PB0 */ gpio_init(GPIOB, GPIO_MODE_OUT_PP, GPIO_OSPEED_2MHZ, GPIO_PIN_0); /* 上电默认灭灯，先给高电平 */ gpio_bit_set(GPIOB, GPIO_PIN_0); }

四个参数依次是：外设端口、工作模式、输出速度档、引脚掩码。关键在于“一次调用只处理同一个端口上属性相同的一组引脚”，同一个端口的 PB0 做输出、PB1 做输入，必须分两次调用。这一点和某些库的“结构体一次配一个引脚”思路不同，抄代码时把两次调用合成一次，结果就是后一次把前一次的配置覆盖掉。

速度档GPIO_OSPEED_2MHZ / 10MHZ / 50MHZ指的是输出驱动器的翻转速率，不是“必须配到最高”。点 LED、驱动继电器这类低速场合配 2MHz 完全够，配 50MHz 反而让边沿变陡、过冲和辐射变差。我吃过一次亏：一块板子上十几个 GPIO 全按例程配成 50MHz，做辐射测试时余量很难看，改回 2MHz 后明显好转。需要高速的只有 SPI、时钟输出、EXMC 数据总线这些。

复用功能的引脚配置也在这里一并说清，串口用 PA9/PA10：

/* TX：复用推挽输出 */ gpio_init(GPIOA, GPIO_MODE_AF_PP, GPIO_OSPEED_50MHZ, GPIO_PIN_9); /* RX：浮空输入，也可以配 GPIO_MODE_IPU 打开内部上拉 */ gpio_init(GPIOA, GPIO_MODE_IN_FLOATING, GPIO_OSPEED_50MHZ, GPIO_PIN_10);

发送脚必须是GPIO_MODE_AF_PP，配成普通推挽输出的话，USART 外设根本接管不了这个引脚，现象是“程序跑了但对方收不到任何数据”。接收脚用浮空或上拉都行，外部有上拉电阻时选浮空，悬空飞线调试时选上拉更稳。

3.2 USART0 中断收发与 printf 重定向

串口初始化有一个顺序问题，很多人踩过：先usart_enable()再去改波特率、字长，配置不生效。正确顺序是先把参数全部设完，最后一步才使能外设：

void bsp_uart0_init(uint32_t baud) { 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); gpio_init(GPIOA, GPIO_MODE_IN_FLOATING, GPIO_OSPEED_50MHZ, GPIO_PIN_10); usart_deinit(USART0); usart_baudrate_set(USART0, baud); usart_word_length_set(USART0, USART_WL_8BIT); usart_stop_bit_set(USART0, USART_STB_1BIT); usart_parity_config(USART0, USART_PM_NONE); usart_hardware_flow_rts_config(USART0, USART_RTS_DISABLE); usart_hardware_flow_cts_config(USART0, USART_CTS_DISABLE); usart_receive_config(USART0, USART_RECEIVE_ENABLE); usart_transmit_config(USART0, USART_TRANSMIT_ENABLE); /* 中断优先级分组在 main 里统一设，这里只给抢占/子优先级 */ nvic_irq_enable(USART0_IRQn, 2, 0); usart_interrupt_enable(USART0, USART_INT_RBNE); /* 所有参数配完才使能 */ usart_enable(USART0); }

usart_baudrate_set内部会拿当前 APB 时钟反算分频值，所以它依赖前面时钟配置正确。nvic_irq_enable的三个参数是中断号、抢占优先级、子优先级，具体分组要在main里用nvic_priority_group_set()先定好，否则优先级数值的含义是漂的。

中断服务函数里只做最轻的事——读数据、丢进环形缓冲，解析放到主循环：

void USART0_IRQHandler(void) { if(usart_interrupt_flag_get(USART0, USART_INT_FLAG_RBNE) != RESET) { /* 读 DATA 寄存器会自动清 RBNE 标志，不用手动清 */ uint8_t ch = (uint8_t)usart_data_receive(USART0); ringbuf_put(&rx_ring, ch); } }

函数名必须和启动文件里的向量表完全一致，USART0_IRQHandler一个字母都不能差，写错了不会报编译错误，只会表现为“中断永远进不来”。

printf 重定向是调试刚需，靠重写fputc实现：

#include <stdio.h> int fputc(int ch, FILE *f) { usart_data_transmit(USART0, (uint8_t)ch); /* 等发送缓冲空，再等一次发送完成，避免最后一位被截断 */ while(RESET == usart_flag_get(USART0, USART_FLAG_TBE)); while(RESET == usart_flag_get(USART0, USART_FLAG_TC)); return ch; }

USART_FLAG_TBE是发送数据寄存器空，USART_FLAG_TC是发送完成。只等 TBE 的话，函数返回时最后一位可能还在移位寄存器里，紧接着进低功耗或者复位就会丢字符。另外在 Keil 里必须勾上 Use MicroLIB，否则标准库会走半主机模式，程序一调用 printf 就卡死在BKPT指令上——这个现象很迷惑，看起来像死机，其实是没连调试器时半主机无法响应。

3.3 DMA 加空闲中断做不定长帧收包

中断逐字节收包在 115200 波特率下勉强够用，上了 921600 或者帧长几百字节，CPU 会被打断得很碎。常规做法是 DMA 搬运加串口空闲中断判帧尾：

#define RX_BUF_SIZE 256 static uint8_t dma_rx_buf[RX_BUF_SIZE]; static volatile uint16_t last_pos = 0; void bsp_uart0_dma_rx_init(void) { dma_parameter_struct dp; rcu_periph_clock_enable(RCU_DMA0); dma_deinit(DMA0, DMA_CH3); /* 必须先做结构体默认值填充，否则未赋值的字段是栈上的随机数 */ dma_struct_para_init(&dp); dp.direction = DMA_PERIPHERAL_TO_MEMORY; dp.memory_addr = (uint32_t)dma_rx_buf; dp.memory_inc = DMA_MEMORY_INCREASE_ENABLE; dp.memory_width = DMA_MEMORY_WIDTH_8BIT; dp.number = RX_BUF_SIZE; dp.periph_addr = (uint32_t)&USART_DATA(USART0); dp.periph_inc = DMA_PERIPH_INCREASE_DISABLE; dp.periph_width = DMA_PERIPH_WIDTH_8BIT; dp.priority = DMA_PRIORITY_HIGH; dma_init(DMA0, DMA_CH3, &dp); /* 循环模式：缓冲区绕圈写，不需要每帧重装传输个数 */ dma_circulation_enable(DMA0, DMA_CH3); dma_channel_enable(DMA0, DMA_CH3); usart_dma_receive_config(USART0, USART_DMA_RECEIVE_ENABLE); /* 空闲中断用来判断“一帧结束” */ usart_interrupt_enable(USART0, USART_INT_IDLE); }

几个参数值得单独交代。periph_addr传的是数据寄存器地址，&USART_DATA(USART0)这个宏展开后就是寄存器地址，不能传USART0本身。number是单次传输个数，循环模式下它决定缓冲区绕圈的周期。DMA 通道不能随便选，USART0 的接收请求固定映射到 DMA0 的某个通道，具体编号要查数据手册的请求映射表，选错了 DMA 一声不响地不工作。

空闲中断的处理要按固定顺序清标志，顺序反了标志清不掉，会反复进中断：

void USART0_IRQHandler(void) { if(usart_interrupt_flag_get(USART0, USART_INT_FLAG_IDLE) != RESET) { /* 清 IDLE 必须先读 STAT 再读 DATA，这是硬件定义的动作序列 */ volatile uint32_t tmp; tmp = USART_STAT0(USART0); tmp = USART_DATA(USART0); (void)tmp; /* 当前写指针 = 缓冲区大小 - DMA 剩余传输个数 */ uint16_t pos = RX_BUF_SIZE - dma_transfer_number_get(DMA0, DMA_CH3); if(pos != last_pos) { uint16_t len = (pos + RX_BUF_SIZE - last_pos) % RX_BUF_SIZE; frame_handle(&dma_rx_buf[last_pos], len); last_pos = pos; } } if(usart_interrupt_flag_get(USART0, USART_INT_FLAG_RBNE) != RESET) { (void)usart_data_receive(USART0); } }

dma_transfer_number_get返回剩余待传输个数，用总数减一下就是已经写入的字节数。取模那一步是为了处理缓冲区绕圈的情况，否则帧跨过缓冲区末尾时长度会算成负数。frame_handle里只做入队或者置标志，别在里面跑协议解析——中断里干重活，下一个空闲中断来了还没处理完，数据就被覆盖了。

4. 高级定时器、ADC 与 EXMC：三个吃底层细节的外设

这三个外设的共同点是：初始化函数写得再对，也可能因为漏了一句“使能”或者时序参数差一档而完全不出波形。例程里的 demo 都只演示最理想的配置，真正落到板子上要补的细节不少。

4.1 TIMER0 互补 PWM：死区与主输出使能

TIMER0 是高级定时器，带互补输出和死区插入，驱动半桥、全桥时必用。先算频率：计数时钟 = 120MHz / (prescaler+1)，PWM 频率 = 计数时钟 / (period+1)。

void bsp_pwm_init(uint32_t freq_hz, uint16_t duty_permille) { timer_parameter_struct tp; timer_oc_parameter_struct oc; rcu_periph_clock_enable(RCU_GPIOA); rcu_periph_clock_enable(RCU_TIMER0); gpio_init(GPIOA, GPIO_MODE_AF_PP, GPIO_OSPEED_50MHZ, GPIO_PIN_8); /* CH0 */ gpio_init(GPIOA, GPIO_MODE_AF_PP, GPIO_OSPEED_50MHZ, GPIO_PIN_7); /* CH0N */ timer_deinit(TIMER0); timer_struct_para_init(&tp); tp.prescaler = 120 - 1; /* 计数时钟 1MHz */ tp.period = (1000000U / freq_hz) - 1; /* 1MHz 分频出目标频率 */ tp.alignedmode = TIMER_COUNTER_EDGE; tp.clockdivision = TIMER_CKDIV_DIV1; tp.counterdirection = TIMER_COUNTER_UP; timer_init(TIMER0, &tp); timer_channel_output_struct_para_init(&oc); oc.outputstate = TIMER_CCX_ENABLE; oc.outputnstate = TIMER_CCXN_ENABLE; /* 互补脚必须显式使能 */ oc.ocpolarity = TIMER_OC_POLARITY_HIGH; oc.ocnpolarity = TIMER_OCN_POLARITY_HIGH; oc.ocidlestate = TIMER_OC_IDLE_STATE_LOW; oc.ocnidlestate = TIMER_OCN_IDLE_STATE_LOW; timer_channel_output_config(TIMER0, TIMER_CH_0, &oc); timer_channel_output_pulse_value_config(TIMER0, TIMER_CH_0, tp.period * duty_permille / 1000); timer_channel_output_mode_config(TIMER0, TIMER_CH_0, TIMER_OC_MODE_PWM0); timer_channel_output_shadow_config(TIMER0, TIMER_CH_0, TIMER_OC_SHADOW_DISABLE); timer_auto_reload_shadow_enable(TIMER0); timer_enable(TIMER0); }

oc.outputnstate设为TIMER_CCXN_ENABLE才有互补脚输出，这个字段在例程里有时候被略过。duty_permille用千分比而不是百分比，是为了避免整数除法丢精度，占空比 12.5% 这种值用千分比能表达成 125。

死区配置单独一个结构体，字段值以计数时钟周期为单位：

void bsp_pwm_deadtime_config(uint16_t deadtime_ticks) { timer_break_parameter_struct brk; timer_break_struct_para_init(&brk); brk.runmodeoffstate = TIMER_ROS_STATE_DISABLE; brk.deadtime = deadtime_ticks; /* 单位：计数时钟周期 */ brk.outputstate = TIMER_CCX_ENABLE; brk.outputnstate = TIMER_CCXN_ENABLE; brk.breakpolarity = TIMER_BREAK_POLARITY_LOW; brk.breakstate = TIMER_BREAK_DISABLE; brk.protectmode = TIMER_PROTECT_DISABLE; brk.iomode = TIMER_IOM_AF; timer_break_config(TIMER0, &brk); /* 少这一句，互补引脚永远是低电平 */ timer_primary_output_config(TIMER0, ENABLE); }

timer_primary_output_config(TIMER0, ENABLE)是最经典的一道坎：配置全对，示波器上两路都没有波形，查半天查不出问题。它是高级定时器的总输出闸门，上电默认关闭。死区时间要按驱动器的开关速度算，我一般先给一个保守值，量完波形再调——用示波器同时看 CH0 和 CH0N 的上升沿间隔，两条沿重叠就是死区不够，间隔太大则效率下降。

4.2 ADC 双通道扫描配 DMA 的启动顺序

ADC 报错最常见的形式不是代码跑崩，而是采样值固定在 4095 或者满量程乱跳。这里贴一套双通道规则组扫描加 DMA 搬运的完整配置：

#define ADC_SAMPLE_COUNT 2 static uint16_t adc_value[ADC_SAMPLE_COUNT]; void bsp_adc_dma_init(void) { dma_parameter_struct dp; rcu_periph_clock_enable(RCU_GPIOA); rcu_periph_clock_enable(RCU_ADC0); rcu_periph_clock_enable(RCU_DMA0); /* ADC 时钟由 APB2 分频而来，必须保证不超过数据手册上限 */ rcu_adc_clock_config(RCU_CKADC_CKAPB2_DIV6); gpio_init(GPIOA, GPIO_MODE_AIN, GPIO_OSPEED_2MHZ, GPIO_PIN_0 | GPIO_PIN_1); adc_deinit(ADC0); adc_mode_config(ADC_MODE_FREE); adc_special_function_config(ADC0, ADC_SCAN_MODE, ENABLE); adc_special_function_config(ADC0, ADC_CONTINUOUS_MODE, ENABLE); adc_data_alignment_config(ADC0, ADC_DATAALIGN_RIGHT); adc_channel_length_config(ADC0, ADC_REGULAR_CHANNEL, ADC_SAMPLE_COUNT); adc_regular_channel_config(ADC0, 0, ADC_CHANNEL_0, ADC_SAMPLETIME_55POINT5); adc_regular_channel_config(ADC0, 1, ADC_CHANNEL_1, ADC_SAMPLETIME_55POINT5); adc_external_trigger_source_config(ADC0, ADC_REGULAR_CHANNEL, ADC0_1_2_EXTTRIG_REGULAR_NONE); adc_external_trigger_config(ADC0, ADC_REGULAR_CHANNEL, ENABLE); adc_dma_mode_enable(ADC0); dma_struct_para_init(&dp); dp.direction = DMA_PERIPHERAL_TO_MEMORY; dp.memory_addr = (uint32_t)adc_value; dp.memory_inc = DMA_MEMORY_INCREASE_ENABLE; dp.memory_width = DMA_MEMORY_WIDTH_16BIT; dp.number = ADC_SAMPLE_COUNT; dp.periph_addr = (uint32_t)&ADC_RDATA(ADC0); dp.periph_inc = DMA_PERIPH_INCREASE_DISABLE; dp.periph_width = DMA_PERIPH_WIDTH_16BIT; dp.priority = DMA_PRIORITY_HIGH; dma_init(DMA0, DMA_CH1, &dp); dma_circulation_enable(DMA0, DMA_CH1); dma_channel_enable(DMA0, DMA_CH1); /* 使能后必须留出稳定时间再校准，这是上下电序列的硬要求 */ adc_enable(ADC0); delay_1ms(2); adc_calibration_enable(ADC0); adc_software_trigger_enable(ADC0, ADC_REGULAR_CHANNEL); }

参数上有三处必须对：rcu_adc_clock_config的分频系数要保证 ADC 时钟落在手册允许范围内，超了读数会明显偏；ADC_SAMPLETIME_55POINT5是采样窗口长度，信号源内阻越高窗口要越长，配太短会出现“通道之间互相串扰”；dp.number必须等于规则通道个数，多了会读到无效数据，少了 DMA 会提前搬完。delay_1ms(2)那一步不要删，刚使能 ADC 时内部参考还在建立，立刻校准得到的偏置是错的。

4.3 EXMC 时序寄存器按纳秒反算周期数

外扩 SRAM、LCD 并口这类场景要用 EXMC。库里给的是周期数，不是纳秒，换算公式是：周期数 = 需要的纳秒数 / 单个 HCLK 周期 × 安全系数。120MHz 下单个 HCLK 约 8.3ns。

void bsp_exmc_sram_init(void) { exmc_norsram_timing_parameter_struct t; exmc_norsram_parameter_struct n; rcu_periph_clock_enable(RCU_EXMC); rcu_periph_clock_enable(RCU_GPIOB); /* 数据/地址线按实际原理图开 */ /* 省略各 GPIO 复用配置，全部配成 GPIO_MODE_AF_PP */ exmc_norsram_timing_parameter_struct_init(&t); /* 器件要求地址建立 25ns，8.3ns 一个周期，取 4 个周期留余量 */ t.asyn_address_setuptime = 4; t.asyn_address_holdtime = 1; t.asyn_data_setuptime = 8; exmc_norsram_struct_para_init(&n); n.norsram_type = EXMC_NORSRAM_TYPE_ASYNC; n.bank = EXMC_BANK0_NORSRAM; n.data_width = EXMC_NORSRAM_DATAPIDTH_16; n.asyn_access_mode = EXMC_ACCESS_MODE_A; n.read_write_timing = &t; n.write_timing = &t; exmc_norsram_init(&n); exmc_norsram_enable(EXMC_BANK0_NORSRAM); }

asyn_access_mode决定读写时序用模式 A 还是模式 B，具体看器件手册的读写波形。asyn_data_setuptime是最容易配小的一个，读周期里数据建立时间不够，现象是读出来偶发某几位翻转错误，跑单次读写测试没问题、跑连续读写就出错，非常难查。稳妥做法是按器件最慢的那个型号的时序算，而不是按典型值。

5. 排查清单：官方例程搬到自己板子上跑不通的五种情形

例程在原厂评估板上跑得好好的，换到自己画的板子就出问题，这类情况占实际调试时间的大头。下面五条按发生频率排，每条都写清现象、原因和解决动作。

5.1 编译、链接与下载阶段的三种翻车

第一条：编译零错误零警告，串口一个字都不出。

现象是程序能下载、能在线调试、断点能停在 main 里，但串口助手一片空白。原因有两个常见分支：一是没勾 Use MicroLIB，fputc走的是半主机模式，程序卡在BKPT上；二是fputc函数签名写错，编译器用了自带版本。解决办法是先确认 Keil 的 Target 选项里勾了 MicroLIB，再把fputc的签名严格写成int fputc(int ch, FILE *f)，同时确认stdio.h已经包含。用在线调试器单步走一遍，看程序是不是停在_sys_exit附近，是的话基本就是这个原因。

第二条：下载时提示目标芯片无法识别，或者提示读保护。

现象是调试器能连上但读不到 ID，或者能读到但下载被拒。原因通常是上一个工程开过读保护，或者 BOOT 引脚被拉到了 ISP 模式，芯片从系统存储器启动而不是从 Flash 启动。解决办法是先用官方提供的工具解除读保护，再检查 BOOT0 的跳线或下拉电阻是否正常。板子上把 BOOT0 直接焊死到高电平的情况不少，调试时怎么都下不进去。

第三条：例程能跑，自己工程一跑就进 HardFault。

现象是刚进 main 没几步就跳进异常处理。最常见的原因是初始化结构体没做默认值填充，函数里读到了栈上的随机字段，比如dma_struct_para_init、timer_struct_para_init这类函数漏调，或者调用了外设初始化却忘了开对应时钟。排查手法是把 HardFault 处理函数改成打印LR和PC的值，反查是哪条指令触发，再对照是不是某个结构体成员指向了非法地址。

5.2 运行阶段的两个隐性冲突

第四条：串口波特率整体偏了一个固定比例，收发都乱码。

现象是配置里写 115200，实际波形对不上，误差远大于晶振精度能解释的范围。原因几乎都是外部晶振没起振，系统时钟退回内部 8MHz RC，而代码还按 120MHz 去算分频。判断方法是把系统时钟从CKOUT脚输出量一下，或者读回rcu_clock_freq_get(CK_SYS)看是不是 8000000。解决要从硬件侧查：晶振负载电容是否匹配、焊盘是否虚焊、起振电阻有没有漏贴。软件上可以在启动时判断外部晶振稳定标志，没稳定就点亮一个错误指示灯，别让系统静默降频继续跑。

第五条：例程里的引脚和自己的板子功能冲突。

现象是某个 demo 一跑，调试器立刻掉线，或者别的外设不工作了。原因是例程占用了调试口引脚（比如把 SWD 的两个脚配成普通 GPIO 去点灯），或者两个例程用了同一组引脚。解决办法是建工程时先做一张引脚占用表，把所有复用功能列清楚，改代码前对照一遍；调试口引脚在正式代码里默认保持复用状态，需要当 GPIO 用时必须先确认调试方式已经切换成别的接口。

6. 从例程到产品代码：一套裁剪与自测的固定动作

例程跑通只是起点，真正要交付的是能长期维护的代码。我的习惯是每引入一个外设，先做一张最小自测表，把“配置是否生效”和“功能是否正确”分开验证，避免一个现象背后藏着两个错误。

本文还有配套的精品资源，点击获取