简介《GD32F10X中文用户手册》2.6 版本2022 年 6 月是 GigaDevice 官方为 GD32F10X 系列 Arm Cortex-M3 32 位 MCU 编写的技术参考文档适合嵌入式驱动开发、固件移植和硬件调试人员查阅。全书从 Cortex-M3 内核、系统架构与存储器映射讲起逐章展开位带操作、片上 SRAM 与 FLASH、引导配置、设备电子签名含 96 位唯一 ID及系统配置寄存器并深入 FMC 闪存控制器、GPIO、定时器、ADC、DMA、CRC、UART、SPI、I2C 等外设的寄存器定义与工作流程。压缩包内仅 1 个 PDF 文件约 26.43MB单册涵盖全部章节配有详细目录、图索引与表索引便于离线检索、随查随用。已有 607 人学习下载。它更像案头工具书查寄存器位定义、确认时钟与复位流程、排查 Flash 擦写与中断配置问题都能按目录快速跳转定位减少反复试错的成本。1. 一份中文手册的真实定位寄存器才是芯片的行为约定很多人把芯片手册当字典用——写代码时遇到某个位不知道填什么翻到对应页查一下查完合上。这种用法只动用了手册三分之一的价值。GD32F10x 这类 Cortex-M3 内核的 MCU外设没有操作系统帮你兜底你写的每一行配置最终都变成对某个地址的一次写操作而手册真正记录的是“这个地址写下去之后芯片内部会发生什么”写错顺序会不会卡死、标志位什么时候置起、时钟没开时读回来是什么。这些编译器不会告诉你调试器也看不出来。搞懂这套控制面的组织方式比记住某个寄存器的位定义有用得多——因为下一个型号换掉的是位定义不换的是“先解锁、再配置、等标志、后上锁”这个节奏。2. 存储器映射与位带4GB 地址空间是怎么被切成功能块的2.1 存储器映射不是一张表而是一套约定Cortex-M3 把 4GB 地址空间做了固定分区这一点在手册 1.3 节的映射图里画得很清楚低端 512MB 给代码区0x20000000 往上是 SRAM0x40000000 往上是外设再往上留给外部存储器与外部设备最后 0xE0000000 开始是内核私有外设NVIC、SysTick、系统控制块都在那一段。这套划分是架构层面定死的不是厂商随手排的所以你在任何一个 Cortex-M3 器件上看到的布局都大体一致换芯片时真正要重新查的是“这个外设挂在哪个偏移”。理解这一点之后很多事情就顺了。所谓“配置一个外设”本质是对某个固定地址写特定的位模式所谓“外设寄存器”本质是一段被硬件监听的内存。手册里那些寄存器地址表不是给编译器看的是给你确认“我操作的到底是不是我以为的那个东西”用的。我见过不少人在调试时直接memcpy一段数据到外设地址区间结果当然是翻车——外设寄存器不支持任意宽度的批量写很多位是只读的有些位写 1 清零、有些写 0 清零跟普通内存的语义完全不是一回事。另一个容易被忽略的点是启动映射。代码区起始地址在复位后不一定指向片上 Flash它取决于引导配置引脚在上电那一刻被采样到的电平组合手册 1.4 节专门讲了这件事。也就是说同一份固件烧进去如果板子上的引导引脚状态不对芯片根本不会从你的代码开始跑。这不是软件问题是硬件状态问题很多“烧录成功但不运行”的现场最后都追到这里。2.2 位带把一个 bit 膨胀成 32 位地址的代价与收益位带是 Cortex-M3 里一个很有意思的设计它把 SRAM 和外设区各自最低的 1MB 拿出来每个 bit 单独映射到别名区的一个 32 位字上。你往别名地址写 1硬件帮你完成“读原字节、置位、写回”这一整套而且整个过程是单次总线写不会被中断打断。为什么值得为这个功能专门划出 32 倍膨胀的地址空间因为并发的读改写是嵌入式里最隐蔽的 bug 来源之一。两个中断同时操作同一个寄存器的不同位用传统的|写法就可能丢更新。位带把“置某一位”变成一条存储指令原子性由硬件保证代码里不用再加临界区。常见的实现思路是这样算地址的#include stdint.h /* 别名区基址SRAM 段与外设段各有一块 */ #define BITBAND_SRAM_BASE 0x22000000UL #define BITBAND_PERI_BASE 0x42000000UL /* * addr : 0x20000000 段或 0x40000000 段内的字节地址 * bit : 0..7要操作的位序号 * 原理区内字节偏移 5 等价于乘 32每字节 8 个 bit每 bit 占 4 字节 * bit 序号 2 等价于乘 4 */ #define BITBAND_ADDR(addr, bit) \ ((((addr) 0xF0000000UL) 0x40000000UL) \ ? (BITBAND_PERI_BASE (((addr) 0x000FFFFFUL) 5) ((bit) 2)) \ : (BITBAND_SRAM_BASE (((addr) 0x000FFFFFUL) 5) ((bit) 2))) #define BITBAND_WORD(addr, bit) (*(volatile uint32_t *)BITBAND_ADDR((addr), (bit))) volatile uint32_t g_flags 0; void set_flag_bit3(void) { /* 编译出来是一条 STR不需要 __disable_irq() 保护 */ BITBAND_WORD((uint32_t)g_flags, 3) 1; }这段代码里三个常量值得解释0x000FFFFF是区内偏移掩码因为只有最低 1MB 参与位带左移 5 位是因为每个原字节的 8 个 bit 各占别名区 4 字节8×432左移 2 位是 bit 序号到字节偏移的换算。把这两步合起来就是别名地址 别名基址 字节偏移×32 bit 序号×4。注意位带只覆盖最低 1MB超出范围的地址算出来的别名指向别处写下去不会报错只会悄悄改错内存。这类问题查起来非常费时间。2.3 电子签名与引导配置芯片怎么回答“我是谁、从哪开始跑”手册 1.5 节讲了两类电子签名存储器容量信息和 96 位设备唯一 ID。容量信息是出厂时写死的程序启动时可以读出来跟自己的链接脚本对一下防止把为大容量型号编译的固件烧进小容量型号——这种事故在产线上不算罕见表现是程序跑到一半跳飞或者擦除越界。96 位唯一 ID 的用途更广设备序列号、密钥派生、授权绑定、产线追溯。它出厂就固定不能改也不会因为擦除 Flash 而丢失。常见的做法是拿它做 HMAC 的输入派生一把跟芯片绑定的密钥固件被复制到别的片子上就跑不起来。/* 具体地址以手册 1.5.2 的表格为准这里用符号占位换型号时只改这一处 */ #define DEVICE_UID_BASE (0x1FFFF7E8UL) void uid_to_string(char *out, uint32_t len) { const volatile uint32_t *uid (const volatile uint32_t *)DEVICE_UID_BASE; /* 96 位 3 个 32 位字直接按字读别按字节拼 */ for (int i 0; i 3 (i * 8 8) len; i) { uint32_t w uid[i]; for (int j 0; j 8; j) { out[i * 8 j] 0123456789ABCDEF[(w (28 - j * 4)) 0xF]; } } }这段代码里的关键是按 32 位字读而不是按字节拼。系统存储区的访问宽度有要求按字节读在一些实现上会得到错位数据。另外这类地址的读取不受读保护影响所以即便 Flash 被保护UID 依然可读这也是它能做设备标识的原因。3. FMC 闪存控制器为什么擦一次 Flash 要走完三段式流程3.1 闪存结构与等待周期读为什么要“等”片上 Flash 的物理结构和 SRAM 完全不同。SRAM 是六个晶体管锁存一个 bit读写速度和内核同频Flash 靠浮栅存电荷读的时候要比较阈值电压写的时候要加高压把电子赶进浮栅或者拉出来。这种物理特性决定了它有两个硬约束读需要时间写需要高压和较长的时间。手册 2.3.1 节的闪存结构表里你能看到主存储块按页划分页大小跟器件密度有关擦除的最小单位是页而不是字节。这一点必须先想清楚你不能“改一个字节”只能“擦掉一整页再整页写回”。所有 Flash 上的参数存储方案本质上都是在跟这个约束做斗争——磨损均衡、日志式追加写、双页轮换都是从这个约束长出来的。读操作的等待周期由 FMC_WS 寄存器控制。主频越高一次 Flash 读取需要的等待周期越多否则内核取指时数据还没准备好。这个寄存器的配置顺序非常关键升频之前先把等待周期加上去降频之后再减回来。顺序反了中间那一小段时间内核在超出 Flash 能力的频率下取指行为不可预测。/* 位域名以手册 2.4.1 的表格为准这里用宏封装便于换型号时统一改 */ static void fmc_ws_set(uint32_t wscnt) { uint32_t ws FMC_WS; ws ~FMC_WS_WSCNT_MASK; ws | (wscnt FMC_WS_WSCNT_MASK); FMC_WS ws; /* 读回确认写没写进去在这里能立刻发现 */ if ((FMC_WS FMC_WS_WSCNT_MASK) ! (wscnt FMC_WS_WSCNT_MASK)) { /* 配置失败通常意味着这组参数超出了手册允许的范围 */ } }这个函数看着简单却是很多“提高主频后随机死机”的根因。死机的表现通常是 HardFault 或者直接跑飞日志里什么都留不下像个黑匣子。我一般的排查顺序是先确认等待周期跟主频是否匹配再确认 PLL 是不是已经稳定最后才怀疑代码逻辑。3.2 双重 KEY 解锁0x45670123 之后为什么还有一步FMC 的控制寄存器上电后是锁定的LK 位置位任何写操作都被忽略。要解锁得往 FMC_KEY0 连续写两个固定值先0x45670123再0xCDEF89AB。很多人第一次看这段会问既然密钥是公开写在手册里的那搞两步有什么意义意义不在保密在于防误操作。单片机跑飞的时候指针可能指向任意地址一次错误的写落在这两个 KEY 地址上的概率极低连续两次按正确顺序命中的概率更低。这是用极小的硬件成本换来的“后悔药”绝大多数野指针不会真的把 Flash 擦掉。同样的思路在选项字节那块还有一套独立的 FMC_OBKEY两把锁分开改普通存储区和改保护配置互不影响。#define FMC_KEY_STEP1 0x45670123UL #define FMC_KEY_STEP2 0xCDEF89ABUL int fmc_unlock(void) { FMC_KEY0 FMC_KEY_STEP1; FMC_KEY0 FMC_KEY_STEP2; /* LK 位没清掉说明序列没被接受后面所有操作都会静默失败 */ if (FMC_CTL0 FMC_CTL0_LK) { return -1; } return 0; } void fmc_lock(void) { FMC_CTL0 | FMC_CTL0_LK; /* 软件置位只有复位才能硬件清除 */ }解锁之后也别急着写。手册 2.3.3 节强调的时序是“先清标志、再配控制、最后启动”。标志位不清你没法区分这次操作成功还是上次遗留的错误。3.3 页擦除与编程的完整时序ADDR0、START、BUSY 三件套擦除一页的流程在手册 2.3.4 节写得很细落到代码上就是四步置 PER 位、把页首地址写进 FMC_ADDR0、置 START 位、轮询 BUSY。这里有两个细节最容易出问题。第一个是 ADDR0 必须落在页边界上写页中间地址不会报错硬件会自己向下对齐结果就是你“以为擦了 A 页实际擦了 B 页”。第二个是 BUSY 的轮询必须真的等到清零中途去读状态寄存器里的其他位读到的可能是上一次的残留值。编程的流程更反直觉没有数据寄存器。你要写的数据直接写到目标地址上硬件拦截这次写操作把它转成 Flash 编程。而且宽度有要求通常必须是半字对齐。int flash_page_rewrite(uint32_t page_addr, const uint16_t *buf, uint32_t halfwords) { uint32_t i; if (fmc_unlock() ! 0) { return -1; } FMC_STAT0 FMC_STAT0_END | FMC_STAT0_PGERR | FMC_STAT0_WRPERR; /* 写 1 清 */ /* 第一步整页擦除 */ FMC_CTL0 | FMC_CTL0_PER; FMC_ADDR0 page_addr; /* 必须是页首否则会向下对齐擦错页 */ FMC_CTL0 | FMC_CTL0_START; while (FMC_STAT0 FMC_STAT0_BUSY) { /* 空转等待不要在这里做别的事 */ } if (FMC_STAT0 (FMC_STAT0_WRPERR | FMC_STAT0_PGERR)) { FMC_CTL0 ~FMC_CTL0_PER; fmc_lock(); return -2; /* 大概率是这页被写保护了 */ } FMC_STAT0 FMC_STAT0_END; FMC_CTL0 ~FMC_CTL0_PER; /* 第二步逐半字编程注意是直接写目标地址不是写数据寄存器 */ FMC_CTL0 | FMC_CTL0_PG; for (i 0; i halfwords; i) { *(volatile uint16_t *)(page_addr i * 2) buf[i]; while (FMC_STAT0 FMC_STAT0_BUSY) { } if (FMC_STAT0 FMC_STAT0_PGERR) { FMC_CTL0 ~FMC_CTL0_PG; FMC_STAT0 FMC_STAT0_PGERR; fmc_lock(); return -3; /* 目标地址没擦干净或者不是半字对齐 */ } FMC_STAT0 FMC_STAT0_END; } FMC_CTL0 ~FMC_CTL0_PG; fmc_lock(); return 0; }这段代码里PGERR的含义值得单独说一句它表示“你试图把 0 写成 1”。Flash 编程只能把 bit 从 1 变 0反过来必须靠擦除。所以如果你忘了先擦除或者这一页只擦了一半编程就会报这个错。看到 PGERR 先别怀疑时序先确认目标页是不是干净的。3.4 选项字节、写保护与读保护一次性操作的风险选项字节是 Flash 里一块特殊区域存的是“芯片怎么保护自己”的配置哪些页禁止擦写、读保护等级、看门狗行为等等。操作它的流程跟主存储区类似但用的是另一套钥匙先通过 FMC_OBKEY 解锁置 OBER 擦除置 OBWEN 使能编程再写入。手册 2.3.7 到 2.3.9 节讲的就是这套。写保护由 FMC_WP 寄存器体现每个 bit 覆盖一组页具体映射关系在手册 2.4.8 节的表里。开启之后对应页的擦除和编程都会置 WRPERR。这个功能在需要保护 bootloader 区不被应用代码误擦时特别有用代价是你自己升级时也得先解保护。读保护是另一个级别的东西。一旦开启调试器连不上普通读取也读不出内容。解除读保护通常会触发整片擦除——这是设计上的取舍如果不能整片擦除就解除保护那保护就形同虚设。我见过有人在产线上批量开了读保护后来想改固件发现每次都得先整片擦除生产节拍直接翻倍。这类配置上线前一定要在样机上完整走一遍全流程包括“如何回退”。注意选项字节的修改一般要复位后才生效写完立刻去读主存储区的保护状态读到的还是旧值。4. RCU 时钟与复位外设从“没电”到“能动”的完整链路4.1 RCU_CTL 与 RCU_CFG0从内部 RC 到 PLL 的切换路径复位之后芯片跑在内部 RC 振荡器上精度一般但胜在起振快、不需要外部器件。要用外部晶振和 PLL就得按顺序动 RCU_CTL 和 RCU_CFG0 这两个寄存器。手册 5.3 节的寄存器表里CTL 管“开不开”CFG0 管“选哪个”。切换路径可以拆成五步开外部晶振、等稳定标志、配 PLL 的源和倍频、开 PLL、等稳定、切系统时钟源、确认切换完成。中间任何一步跳过稳定标志的等待都可能切到一个还没起振的时钟上后果是内核直接停摆连 HardFault 都来不及进。int clock_switch_to_pll(uint32_t pll_mul, uint32_t ws_for_target) { uint32_t timeout; /* 1. 开外部晶振位域名以手册 5.3.1 为准 */ RCU_CTL | RCU_CTL_HXTALEN; timeout 0x5FFFF; while (!(RCU_CTL RCU_CTL_HXTALSTB)) { if (--timeout 0) { return -1; /* 晶振没起振先查硬件 */ } } /* 2. 配置 PLL源选外部晶振设置倍频 */ RCU_CFG0 ~(RCU_CFG0_PLLSEL | RCU_CFG0_PLLMF); RCU_CFG0 | (RCU_CFG0_PLLSEL | ((pll_mul - 2) 18)); /* 3. 开 PLL 并等稳定 */ RCU_CTL | RCU_CTL_PLLEN; timeout 0x5FFFF; while (!(RCU_CTL RCU_CTL_PLLSTB)) { if (--timeout 0) { return -2; } } /* 4. 关键顺序先加等待周期再切时钟源 */ fmc_ws_set(ws_for_target); /* 5. 切系统时钟源并等状态位确认 */ RCU_CFG0 ~RCU_CFG0_SCS; RCU_CFG0 | RCU_CFG0_SCS_PLL; timeout 0x5FFFF; while ((RCU_CFG0 RCU_CFG0_SCSS) ! RCU_CFG0_SCSS_PLL) { if (--timeout 0) { return -3; } } return 0; }PLL 倍频字段的编码方式各个型号不完全一样有的用“倍频值减 2”有的直接编码写的时候一定要对着手册 5.3.2 的表格逐位核。至于等待周期的具体数值手册 2.4.1 节给出了频率与 WS 的对应关系别凭感觉填。4.2 使能寄存器分组的理由APB1、APB2、AHB 为什么不能合并RCU 里外设时钟使能被拆成 AHBEN、APB2EN、APB1EN 三组不是设计者偷懒没合并而是这三条总线本身的能力不同。AHB 速度最高挂 DMA、SRAM 接口这类APB2 次之挂 GPIO、AFIO、ADC、USART0 这类APB1 最低挂定时器、I2C、SPI 这些。分组的本质是让时钟域和总线域对齐低速外设不用跟着高频总线一起翻转动态功耗就是这么省下来的。写代码时的直接后果是每个外设的使能位在不同寄存器里写错一个就是“外设毫无反应”。更隐蔽的是复用功能比如用某个引脚做串口不只要开 GPIO 时钟和串口时钟还得开 AFIO 时钟否则重映射配置写不进去。/* 开三组时钟GPIOA、AFIO 在 APB2定时器在 APB1DMA 在 AHB */ RCU_APB2EN | RCU_APB2EN_PAEN | RCU_APB2EN_AFEN; RCU_APB1EN | RCU_APB1EN_TIMER2EN; RCU_AHBEN | RCU_AHBEN_DMA0EN; /* 如果这个外设之前被复位过还要显式解除复位 */ RCU_APB2RST ~RCU_APB2RST_PARST;最后那行解复位操作是另一个高频翻车点。复位寄存器置位后外设停在复位态你后面所有配置都写不进去表现为“时钟开了、寄存器写了、就是不工作”。看到这种现象先把对应的 RST 位读出来确认一下。4.3 RSTSCK复位源识别与时钟源状态的双重身份RCU_RSTSCK 这个寄存器名字有点怪因为它同时承担了两个职责记录上次复位是谁引起的以及反映备份域的时钟状态。前者对故障诊断极有价值——设备在野外重启了你总得知道是掉电、看门狗还是软件主动复位。const char *last_reset_cause(void) { uint32_t rst RCU_RSTSCK; const char *cause unknown; if (rst RCU_RSTSCK_PORRSTF) cause power-on; else if (rst RCU_RSTSCK_SWRSTF) cause software; else if (rst RCU_RSTSCK_FWDTRSTF) cause iwdg; else if (rst RCU_RSTSCK_WWDTRSTF) cause wwdg; else if (rst RCU_RSTSCK_LPRSTF) cause low-power; else if (rst RCU_RSTSCK_EPRSTF) cause external-pin; /* 写 1 清全部标志为下次启动做准备 */ RCU_RSTSCK | RCU_RSTSCK_RSTFC; return cause; }这段代码要放在main的最开头执行因为你一旦清了标志信息就没了。配合备份寄存器把复位原因累计存起来就能看到“这台设备一周内被看门狗复位了 37 次”这种信息排查方向立刻就清楚了。4.4 EXTI 的中断与事件双路径为什么事件不经过 NVIC外部中断控制器在手册第 6 章它的框图里有一条容易被忽略的分叉同一个触发源可以走中断路径进 NVIC也可以走事件路径直接去触发别的外设。事件路径不经过 CPU不产生中断服务程序纯粹是硬件之间的连线。这个设计的意义在于把“响应”和“计算”解耦。比如某个引脚的状态变化需要启动一次 ADC 采样用事件路径可以让 EXTI 直接触发 ADCCPU 完全不用醒如果用中断路径CPU 得先进中断、再配 ADC、再退出多花几十个周期。在对时序和功耗都敏感的场景里这个差别不小。void exti_key_init(void) { RCU_APB2EN | RCU_APB2EN_PAEN | RCU_APB2EN_AFEN; gpio_mode_set(GPIOA, GPIO_MODE_INPUT, GPIO_PUPD_PULLUP, GPIO_PIN_0); /* AFIO 里选 EXTI0 的输入端口不写这步用的可能是默认端口 */ AFIO_EXTISS0 (AFIO_EXTISS0 ~AFIO_EXTISS0_EXTI0_SS) | AFIO_EXTISS0_EXTI0_SS_PA; EXTI_INTEN | EXTI_INTEN_EXTI0; /* 中断路径会进 NVIC */ EXTI_RTEN | EXTI_RTEN_EXTI0; /* 上升沿触发 */ nvic_irq_enable(EXTI0_IRQn, 2, 0); }注意 EXTI 线的编号和 GPIO 引脚号是绑定的EXTI0 只能接某个端口的 0 号引脚不能接 1 号。你要用多个引脚就得占用多条 EXTI 线而 EXTI5 到 EXTI9 共享一个中断入口EXTI10 到 EXTI15 也是进中断后还得自己读标志位判断是哪条线触发的。5. 避坑与排查手册上一句话、实际会翻车的五个现场5.1 闪存操作类擦除“成功”了数据却没变现象调用擦除函数返回 0读回来数据还在或者只有一部分变成 0xFF。原因三种可能按概率排序——目标页被 FMC_WP 写了保护擦除操作被硬件拒绝但代码没检查 WRPERR地址没落在页首硬件向下对齐擦掉的是前一页轮询 BUSY 时读的是缓存的变量而不是寄存器循环被编译器优化掉了。解决把 STAT0 里的三个错误标志全部检查一遍不要只看返回值地址传进来先做页对齐断言轮询处的寄存器访问加volatile或者直接用库函数里的等待实现。这类问题最坑的地方在于它不报错只是静默失效所以检查错误标志这一步不能省。5.2 闪存操作类编程后读回数据错位或全 0xFF现象写进去的数组读回来整体偏移一个字节或者干脆全是 0xFF。原因数据宽度不对。这类 Flash 的编程单位是半字你按字节指针写会触发对齐错误或者只写进去一半另一个原因是忘了先擦除直接往有数据的页上写PGERR 被忽略后读到的还是旧内容。解决统一用uint16_t *访问目标区长度按半字算写之前先确认这一页是 0xFF不是就先擦。我一般会在编程函数开头加一段校验扫描目标区域发现非 0xFF 直接返回错误而不是硬写。5.3 时钟与复位类时钟开了外设还是不动现象RCU_APBxEN里对应的位置了外设寄存器写进去读出来还是 0或者配置完毫无反应。原因最常见的是外设还停在复位态。复位寄存器置位后外设被按住你写什么都被忽略。其次是选错了总线分组——比如以为串口在 APB1 其实在 APB2开了另一个同名外设的时钟。第三种是复用功能没开 AFIO 时钟重映射配置写不进去引脚还连着默认功能。**本文还有配套的精品资源点击获取