📚 课程目录第3章外设寄存器与内存映射

3、外设寄存器与内存映射：Rust中如何安全地访问外设寄存器

嵌入式开发说白了就是跟寄存器打交道。你想想看，CPU要控制GPIO的高低电平、配置UART的波特率、启动DMA传输——所有这些操作，最终都要落到对特定内存地址的读写上。这就是所谓的内存映射I/O（MMIO）。

但问题来了：在Rust里直接操作地址，编译器会怎么想？它会觉得「这地址没人用啊，优化掉算了」。嗯，这就是我们今天要解决的核心矛盾。

3.1 内存映射I/O的基本概念

外设寄存器被映射到CPU的地址空间中。每个寄存器对应一个固定的地址。比如STM32F4的GPIOA_ODR寄存器，地址是0x40020014。你往这个地址写1，PA0引脚就输出高电平。

听起来很简单对吧？但这里有个坑：寄存器的值可能被硬件改变。你读一个状态寄存器，硬件可能在下一秒就更新了它。编译器不知道这件事，它会认为「这个地址的值没变过」，然后优化掉你的第二次读取。

核心要点：外设寄存器不是普通内存。它们的值会因硬件事件而改变，且每次读写可能有副作用。编译器不能优化这些操作。

3.2 为什么需要volatile

volatile关键字就是告诉编译器：「别耍小聪明，每次读写都给我老老实实执行」。在C语言里，你写volatile uint32_t *reg = ...。在Rust里，我们用core::ptr::read_volatile和core::ptr::write_volatile。

我在项目中遇到过一个问题：调试一个I2C驱动时，状态寄存器总是读不到正确的值。查了半天，发现是编译器把第二次读取优化掉了——它觉得第一次读到的值已经够用了。加上volatile之后，问题立刻消失。

警告：volatile不是原子操作！它只保证编译器不优化，不保证多核或中断上下文中的数据一致性。如果需要原子性，还得配合内存屏障或原子指令。

3.3 Rust中的安全抽象

裸指针操作是unsafe的。但我们可以用Rust的类型系统，把这种不安全封装在安全的API后面。我个人的习惯是：每个外设对应一个结构体，寄存器用volatile_cell或core::ptr封装。

来看一个典型的GPIO输出寄存器封装：

use core::ptr;

/// GPIO输出数据寄存器
pub struct GpioOdr {
    address: usize,
}

impl GpioOdr {
    /// 创建一个新的寄存器访问器
    /// 
    /// # Safety
    /// 调用者必须保证address是有效的MMIO地址
    pub const unsafe fn new(address: usize) -> Self {
        Self { address }
    }

    /// 读取当前输出值
    pub fn read(&self) -> u32 {
        unsafe { ptr::read_volatile(self.address as *const u32) }
    }

    /// 写入输出值
    pub fn write(&self, value: u32) {
        unsafe { ptr::write_volatile(self.address as *mut u32, value) }
    }

    /// 修改特定位（读-改-写）
    pub fn modify<F>(&self, f: F)
    where
        F: FnOnce(u32) -> u32,
    {
        let old = self.read();
        let new = f(old);
        self.write(new);
    }
}

你看，read和write内部用了volatile操作，但对外暴露的是安全接口。调用者不需要关心底层细节。这就是Rust的零成本抽象——运行时和直接操作指针一样快，但编译时保证了类型安全。

3.4 寄存器位域操作

实际开发中，我们经常要操作寄存器的某几位。比如配置一个UART的波特率寄存器，可能只需要修改低16位。我建议用位域结构体来管理：

/// USART控制寄存器1的位域定义
pub struct UsartCr1 {
    reg: GpioOdr, // 复用上面的寄存器抽象
}

impl UsartCr1 {
    /// 使能USART
    pub fn enable(&self) {
        self.reg.modify(|v| v | (1 << 13)); // UE位在bit 13
    }

    /// 设置数据位长度
    pub fn set_data_bits(&self, bits: DataBits) {
        self.reg.modify(|v| {
            let m_bits = match bits {
                DataBits::Eight => 0,
                DataBits::Nine => 1,
            };
            (v & !(1 << 12)) | (m_bits << 12) // M位在bit 12
        });
    }
}

pub enum DataBits {
    Eight,
    Nine,
}

我的经验：位域操作最容易出错的地方是掩码计算。我习惯在注释里写明每个位的功能，或者用常量命名。比如const UE_BIT: u32 = 13;，这样代码自文档化，别人一看就懂。

3.5 内存映射的完整示例

下面是一个完整的GPIO外设驱动骨架。它展示了如何把寄存器组映射到一个结构体上：

use core::ptr;

/// GPIO寄存器组的内存布局
#[repr(C)]
pub struct GpioRegs {
    pub moder: u32,   // 模式寄存器，偏移0x00
    pub otyper: u32,  // 输出类型寄存器，偏移0x04
    pub ospeedr: u32, // 输出速度寄存器，偏移0x08
    pub pupdr: u32,   // 上拉/下拉寄存器，偏移0x0C
    pub idr: u32,     // 输入数据寄存器，偏移0x10
    pub odr: u32,     // 输出数据寄存器，偏移0x14
    pub bsrr: u32,    // 置位/复位寄存器，偏移0x18
    pub lckr: u32,    // 锁定寄存器，偏移0x1C
    pub afrl: u32,    // 复用功能低寄存器，偏移0x20
    pub afrh: u32,    // 复用功能高寄存器，偏移0x24
}

/// GPIO外设
pub struct Gpio {
    regs: &'static mut GpioRegs,
}

impl Gpio {
    /// 创建一个GPIO实例
    /// 
    /// # Safety
    /// base_addr必须是有效的GPIO基地址
    pub unsafe fn new(base_addr: usize) -> Self {
        Self {
            regs: &mut *(base_addr as *mut GpioRegs),
        }
    }

    /// 设置引脚为输出模式
    pub fn set_output(&self, pin: u8) {
        let mask = 0b11 << (pin * 2);
        let value = 0b01 << (pin * 2); // 01 = 通用输出
        unsafe {
            ptr::write_volatile(
                &self.regs.moder as *const u32 as *mut u32,
                (ptr::read_volatile(&self.regs.moder) & !mask) | value,
            );
        }
    }

    /// 输出高电平
    pub fn set_high(&self, pin: u8) {
        unsafe {
            ptr::write_volatile(
                &self.regs.bsrr as *const u32 as *mut u32,
                1 << pin,
            );
        }
    }

    /// 输出低电平
    pub fn set_low(&self, pin: u8) {
        unsafe {
            ptr::write_volatile(
                &self.regs.bsrr as *const u32 as *mut u32,
                1 << (pin + 16),
            );
        }
    }
}

这里用了#[repr(C)]保证结构体字段的内存布局和硬件寄存器偏移一致。你想想看，如果Rust按自己的规则重排字段，那地址就对不上了——这是嵌入式开发里最容易踩的坑之一。

3.6 知识体系总览

下面这张图总结了本章的核心逻辑：从硬件寄存器到Rust安全抽象的全链路。

3.7 常见陷阱与最佳实践

做了这么多年嵌入式，我总结了几条血的教训：

陷阱	后果	解决方案
忘记volatile	编译器优化导致读写被跳过	始终使用`read_volatile`/`write_volatile`
结构体字段重排	寄存器地址错位	使用`#[repr(C)]`保证布局
非原子读-改-写	中断中修改导致数据竞争	使用临界区或CAS操作
指针类型错误	未定义行为	明确使用`const u32`或`mut u32`

我曾经踩过的坑：有一次写SPI驱动，为了图方便直接用了core::ptr::read而不是read_volatile。结果在-O2优化下，状态寄存器的轮询循环直接变成了死循环——编译器认为寄存器值不会变，把读取提到了循环外面。从那以后，我所有外设寄存器访问都强制用volatile版本，哪怕只是读一次。

3.8 小结

外设寄存器访问是嵌入式Rust的基石。记住三个要点：

volatile不能省——编译器优化是嵌入式开发的头号敌人
类型安全是Rust的礼物——用结构体和枚举把unsafe关在笼子里
位域操作要谨慎——掩码和移位最容易出错，多写注释

掌握了这些，你就能安全地操作任何外设寄存器了。下一层，我们会把这些知识用到实际的DMA传输配置中——到时候你会发现，今天的抽象层会让DMA编程变得异常清爽。