mmio-and-bit-manipulation

MMIO 与位操作

用途

指导 Agent 安全地使用内存映射 I/O：volatile 语义、读-改-写模式、位域陷阱、对齐与字节序，以及适用于裸机驱动的可移植寄存器访问宏。

适用场景

• 不使用 HAL 编写外设寄存器驱动
• 修复间歇性寄存器损坏或读取陈旧值的问题
• 用显式掩码替代 C 位域
• 在小端 MCU 之间移植驱动
• 审查 ISR 与主线代码对寄存器的访问

工作流

1. MMIO 基础

外设寄存器位于 CPU 内存映射中的固定地址。编译器不得缓存读写操作。

#include <stdint.h>

#define PERIPH_BASE   0x40000000U
#define GPIOA_MODER   (*(volatile uint32_t *)(PERIPH_BASE + 0x20000U))

限定符	效果
volatile	每次访问都强制执行加载/存储操作——硬件访问必需
const volatile	只读硬件（少见）
普通 uint32_t *	错误——编译器可能会将访问优化掉

2. 读-改-写宏

#define REG32(addr)        (*(volatile uint32_t *)(addr))
#define REG_SET(addr, mask)   (REG32(addr) |= (mask))
#define REG_CLR(addr, mask)   (REG32(addr) &= ~(mask))
#define REG_TOGGLE(addr, mask) (REG32(addr) ^= (mask))
#define REG_WRITE(addr, val)  (REG32(addr) = (val))
#define REG_READ(addr)        (REG32(addr))

良好 — 当寄存器支持时，单个位更新可表达原子操作意图：

#define GPIOA_BSRR  REG32(0x40020018U)
GPIOA_BSRR = (1U << 5);        /* set PA5 */
GPIOA_BSRR = (1U << (5+16));   /* reset PA5 — STM32 BSRR pattern */

不良 — 在中断共享的寄存器上执行非原子的 RMW：

uint32_t v = REG_READ(GPIOA_MODER);
v |= (1U << 10);
REG_WRITE(GPIOA_MODER, v);  /* ISR may interleave — lost update */

修复方法：短暂禁用 IRQ、使用硬件置位/清零寄存器，或在可用时使用 LL 原子位带操作。

3. 位域陷阱

/* Bad — layout is implementation-defined, not portable */
typedef struct {
    uint32_t mode  : 2;
    uint32_t type  : 1;
    uint32_t speed : 2;
} gpio_moder_bits_t;

优先使用显式掩码：

#define GPIO_MODER_MODE0_SHIFT   0
#define GPIO_MODER_MODE0_MASK    (3U << GPIO_MODER_MODE0_SHIFT)
#define GPIO_MODER_MODE0_VAL(n)  ((n) << GPIO_MODER_MODE0_SHIFT)

REG32(GPIOA_MODER) = (REG32(GPIOA_MODER) & ~GPIO_MODER_MODE0_MASK)
                   | GPIO_MODER_MODE0_VAL(1);  /* output */

4. 字节序与对齐

• Cortex-M 和大多数 MCU：小端序 — 在按字对齐的地址访问 MMIO uint32_t
• 未对齐的 uint32_t 访问在 ARMv7-M+ 上可能触发故障
• 8 位寄存器：使用 volatile uint8_t，并指定正确的字节通道地址

#define REG8(addr)  (*(volatile uint8_t *)(addr))

5. 内存屏障（需要时）

/* After configuring peripheral before first use */
__DSB();
__ISB();

/* After DMA setup, before enabling channel */
__DMB();

在 Cortex-M 上使用 CMSIS 屏障（core_cm4.h）。

6. Agent 使用示例

/mmio-and-bit-manipulation Safe pattern to set bit 3 without affecting other bits in ISR context
/mmio-and-bit-manipulation Why must peripheral pointers be volatile?

常见问题

症状	原因	修复方法
寄存器写入无效	地址错误／时钟被门控	先启用外设时钟
位随机翻转	RMW 与 ISR 竞争	使用 BSRR 风格的原子寄存器或临界区
访问时发生 HardFault	未对齐或总线受保护	按照数据手册匹配访问宽度
读取操作被优化掉	缺少 volatile	使用 volatile uint32_t
位域值错误	编译器打包方式出乎意料	使用移位／掩码宏

相关技能

• skills/baremetal/peripherals-from-datasheet — 提取寄存器映射
• skills/baremetal/gpio-baremetal — GPIO 寄存器模式
• skills/low-level-programming/assembly-arm — 内联汇编屏障
• skills/embedded/linker-scripts — 外设内存映射区域