C 语言结构体对齐与 STM32 寄存器映射：为什么偏移算错会读到错寄存器

在 STM32 裸机开发里，寄存器映射最常见的错误不是写错了某个位，而是把结构体的偏移算错了：代码看起来一切正常，读回来的却根本不是目标寄存器。本文从 GPIO 映射讲起，说明混宽寄存器为什么会“捣乱”，以及如何用保留字段和编译期断言把偏移锁死。

一、STM32 GPIO 结构体映射写法

以 GPIOA 为例，STM32 的 GPIO 寄存器是连续排列的 32 位寄存器，基地址为 0x48000000。常见的映射写法如下：

typedef struct {
    volatile uint32_t MODER;    /* 0x00：模式寄存器 */
    volatile uint32_t OTYPER;   /* 0x04：输出类型寄存器 */
    volatile uint32_t OSPEEDR;  /* 0x08：输出速度寄存器 */
    volatile uint32_t PUPDR;    /* 0x0C：上下拉寄存器 */
    volatile uint32_t IDR;      /* 0x10：输入数据寄存器 */
    volatile uint32_t ODR;      /* 0x14：输出数据寄存器 */
} GPIO_TypeDef;

#define GPIOA ((GPIO_TypeDef *)0x48000000u)

这样写的前提是：所有成员都是 32 位，对齐要求一致，偏移自然就是 0x00、0x04、0x08……一旦某个外设的寄存器宽度不再统一，这个前提就失效了。

二、混宽寄存器对齐捣乱的例子

假设某个外设的寄存器布局是这样的：32 位的控制寄存器 CR 在 0x00，16 位的状态寄存器 SR 在 0x04，8 位的标志寄存器 FLAG 在 0x06，下一个寄存器 NEXT 在硬件手册上位于 0x07。如果直接按直觉写结构体：

typedef struct {
    volatile uint32_t CR;   /* 0x00 */
    volatile uint16_t SR;   /* 0x04 */
    volatile uint8_t  FLAG; /* 0x06 */
    volatile uint32_t NEXT; /* 你以为是 0x07 */
} Bad_TypeDef;

问题就出在这里：编译器为了让 32 位的 NEXT 按 4 字节对齐，会在 FLAG 后面插入 3 字节填充。于是 NEXT 的实际偏移从 0x07 变成了 0x0C，代码访问的根本不是手册上的 NEXT 寄存器，而是后面 5 个字节之外的地址。读到的是错寄存器，写进去的也可能改动了不该动的位，调试时现象往往表现为“时好时坏”或者“改了没反应”。

更隐蔽的是，这种错误在仿真或单步调试里不一定立刻暴露：如果那片地址恰好可读，程序不会崩溃，只会得到一个看似合理却完全错误的值。

三、编译期 static_assert 与保留字段的正确写法

正确的做法是：对照手册，把填充显式写出来，不要交给编译器“猜”。

typedef struct {
    volatile uint32_t CR;        /* 0x00 */
    volatile uint16_t SR;        /* 0x04 */
    volatile uint8_t  FLAG;      /* 0x06 */
    volatile uint8_t  RESERVED[3]; /* 0x07-0x09：显式保留，补齐到 0x0C */
    volatile uint32_t NEXT;      /* 0x0C：与手册一致 */
} Good_TypeDef;

_Static_assert(sizeof(Good_TypeDef) == 16, "Good_TypeDef size mismatch");
_Static_assert(offsetof(Good_TypeDef, NEXT) == 0x0C, "NEXT offset mismatch");

这里有两个关键点。第一，RESERVED[3] 把填充变成了文档：后来读代码的人一眼就能看出 0x07 到 0x09 是故意留空的，而不是编译器悄悄加的。第二，static_assert 在编译期就把总大小和关键偏移卡住：一旦有人改了成员顺序、改了宽度或者换了编译器对齐策略，编译立刻失败，而不是等到上板之后才用错寄存器来“提醒”你。

对 GPIO 这样全是 32 位寄存器的外设，同样建议加 sizeof 断言：结构体总大小应当等于手册给出的寄存器块大小，差一个字节都说明映射已经偏了。

四、volatile 不能省，位操作不要用位域

寄存器映射还有两个经常被忽视的规则。

第一，成员必须加 volatile。寄存器值会随硬件状态变化，编译器如果不知道这一点，就可能把轮询标志位的循环优化成只读一次，或者把连续两次写合并成一次。昨天的文章已经讲过 volatile 与编译器优化的关系，这里再强调一次：映射寄存器时，volatile 不是装饰，是正确性的前提。

第二，不要用位域映射寄存器位。C 语言没有规定位域的排列顺序、跨字节行为和读写粒度，不同编译器、不同优化级别下可能生成不同的访问方式，有的还会先读整个字、改一位再写回，误触只写清除的标志位。稳妥的做法是用掩码移位：

GPIOA->ODR |= (1u << 5);   /* 置位 PA5 */
GPIOA->ODR &= ~(1u << 5);  /* 清除 PA5 */
if (GPIOA->IDR & (1u << 5)) {
    /* 读取 PA5 输入 */
}

掩码移位语义明确、移植性好，而且读改写的过程完全在程序员掌控之中。

五、结论

第一，混宽寄存器一定要显式留保留字段：不要依赖编译器自动填充，把手册上的空洞原样写进结构体。第二，总大小和关键偏移要用编译期断言卡住：sizeof 与 offsetof 一旦偏离手册，编译就应当失败。第三，成员加 volatile、位操作用掩码不用位域：前者防止编译器把硬件访问优化掉，后者避免位域布局不确定带来的误操作。

偏移算错的代价往往不是编译报错，而是读到错寄存器后的一连串“玄学”故障。把保留字段和断言写在前面，是 STM32 寄存器映射最便宜的保险。