3. 外设寄存器抽象：使用 volatile_register crate、定义寄存器结构体、实现读写方法

上一章我们聊了 MMIO 地址映射，说白了就是把外设的寄存器暴露给 CPU 去访问。但直接拿裸指针操作寄存器，在 Rust 里是件很「危险」的事——编译器会优化掉你以为必要的读写，甚至乱序执行。我早年做 STM32 裸机开发时就吃过这个亏，一个状态寄存器读出来永远是 0，查了两天才发现是编译器把 volatile 读给优化掉了。

所以这一章，我们来解决这个问题。核心思路就三个：用 volatile 保证读写不被优化、用结构体描述寄存器布局、用安全方法封装操作。

3.1 为什么需要 volatile？

先看一个反面教材。假设我们有一个 DMA 状态寄存器，地址是 0x4000_0000：

let status_ptr = 0x4000_0000 as *const u32;
loop {
    let status = unsafe { *status_ptr };
    if status & 0x01 != 0 {
        break;
    }
}

这段代码在 Debug 模式下可能能跑，Release 模式下大概率死循环。为什么？因为编译器发现 *status_ptr 读出来的值在循环里没被修改，它觉得「这值不会变啊，我帮你优化成常量吧」。于是 status 永远等于第一次读到的值。

这就是典型的缺少 volatile 语义。硬件寄存器可能随时被外设改变，编译器不知道这件事。我们需要告诉编译器：「每次读都去内存里取，别自作聪明。」

3.2 volatile_register crate 登场

Rust 标准库提供了 core::ptr::read_volatile 和 write_volatile，但每次都要写 unsafe 块，很烦人。volatile_register crate 就是来解决这个痛点的。它提供了三个基本类型：

类型	对应硬件寄存器	方法
RW<T>	可读可写寄存器	read()、write()、modify()
RO<T>	只读寄存器	read()
WO<T>	只写寄存器	write()

每个类型内部都包装了一个 UnsafeCell<T>，保证 volatile 语义。用法很简单：

use volatile_register::{RW, RO, WO};

// 假设 DMA 通道 0 的基地址
let base = 0x4000_0000 as *mut u32;

// 用指针偏移模拟寄存器地址
let status_reg = base.add(0x00) as *const RO<u32>;
let ctrl_reg   = base.add(0x04) as *mut RW<u32>;

unsafe {
    let status = (*status_reg).read();
    (*ctrl_reg).write(0x01);
}

嗯，这里要注意：read() 和 write() 内部已经帮你做了 volatile 操作，但指针转换本身还是 unsafe 的。这个 unsafe 我们后面会用结构体封装掉。

3.3 定义寄存器结构体

我个人习惯的做法是：为每个外设定义一个结构体，成员就是它的寄存器。这样既清晰，又能利用 Rust 的类型系统做编译期检查。

以 DMA 控制器为例，假设它有 8 个通道，每个通道有 4 个寄存器：

use volatile_register::{RW, RO};

/// DMA 通道寄存器块
#[repr(C)]
pub struct DmaChannel {
    /// 状态寄存器 (只读)
    pub status: RO<u32>,
    /// 控制寄存器 (读写)
    pub ctrl:   RW<u32>,
    /// 源地址寄存器 (读写)
    pub src:    RW<u32>,
    /// 目的地址寄存器 (读写)
    pub dst:    RW<u32>,
}

/// DMA 控制器顶层结构
#[repr(C)]
pub struct Dma {
    /// 通道 0 ~ 7
    pub channels: [DmaChannel; 8],
    /// 全局配置寄存器
    pub global_cfg: RW<u32>,
}

这里有几个关键点：

• #[repr(C)]：强制按 C 语言的内存布局排列，保证字段顺序和偏移量跟硬件手册一致。没有这个属性，Rust 编译器可能会重排字段。
• 数组表示多个通道：如果每个通道的寄存器布局相同，用数组最省事。我在项目中遇到过有人把 8 个通道写成 8 个独立字段，代码膨胀得没法看。
• 类型即文档：看到 RO<u32> 就知道这个寄存器只能读，RW<u32> 可读可写。比看数据手册还直观。

3.4 实现读写方法

结构体定义好了，怎么用？直接暴露字段是 unsafe 的，因为用户可能写出 dma.channels[0].ctrl.write(0xFFFFFFFF) 这种危险操作。我们需要封装安全的方法。

我一般会为每个外设实现一个 new() 方法和若干操作函数：

impl Dma {
    /// 从基地址创建 DMA 实例
    ///
    /// # Safety
    /// - `base` 必须指向有效的 DMA 寄存器地址范围
    /// - 调用者需保证没有其他代码同时访问该地址
    pub unsafe fn new(base: usize) -> &'static mut Self {
        &mut *(base as *mut Self)
    }

    /// 启动指定通道的传输
    pub fn start_channel(&self, ch: usize) {
        if ch >= 8 {
            return; // 或者 panic!
        }
        // 读取当前控制值，置位使能位，再写回
        unsafe {
            self.channels[ch].ctrl.modify(|v| v | 0x01);
        }
    }

    /// 检查通道是否传输完成
    pub fn is_channel_done(&self, ch: usize) -> bool {
        if ch >= 8 {
            return false;
        }
        unsafe {
            self.channels[ch].status.read() & 0x01 != 0
        }
    }
}

注意 modify() 方法——这是 RW<T> 提供的「读-改-写」原子操作。它先 volatile 读，然后执行闭包，最后 volatile 写回。比手动 read() + 修改 + write() 更安全，因为中间不会被中断打断（单核下）。

3.5 完整示例：DMA 通道配置

把上面所有东西串起来，写一个完整的 DMA 通道配置流程：

/// 配置 DMA 通道进行内存到内存传输
pub fn config_mem_to_mem(dma: &Dma, ch: usize, src: u32, dst: u32, len: u32) {
    if ch >= 8 {
        panic!("DMA channel {} out of range", ch);
    }

    let chan = &dma.channels[ch];

    unsafe {
        // 1. 设置源地址
        chan.src.write(src);
        // 2. 设置目的地址
        chan.dst.write(dst);
        // 3. 配置控制寄存器：
        //    - bit 0: 使能
        //    - bit 1: 传输完成中断使能
        //    - bit 8-15: 传输长度
        chan.ctrl.write(0x01 | (1 << 1) | ((len & 0xFF) << 8));
    }
}

这段代码看起来简单，但背后做了三件重要的事：

1. 边界检查：通道号越界直接 panic，避免访问非法内存。
2. 位域操作：用移位和掩码精确控制寄存器位，不干扰其他位。
3. volatile 保证：每次 write() 都真正写到了硬件寄存器。

3.6 知识结构总览

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

从下往上看，每一层都在前一层的基础上增加了安全性和易用性。最底层是裸硬件，最顶层是调用者只需要关心「做什么」，不需要关心「怎么做」。

3.7 避坑指南

最后分享几个我实际项目中遇到的教训：

• 不要用 std::ptr::write 代替 volatile_register：write 不保证 volatile，Release 模式下会被优化掉。我见过有人为了省一个依赖自己手写 volatile，结果漏了 core::sync::atomic::compiler_fence，一样出问题。
• 结构体字段顺序必须和手册一致：#[repr(C)] 只保证按声明顺序排列，但如果你把 src 和 dst 写反了，DMA 会把数据从错误地址搬走。调试这种问题很痛苦。
• 小心位域重叠：有些芯片的寄存器位域定义很奇葩，比如 bit 0-3 是 A 功能，bit 2-5 是 B 功能。这种时候用 modify() 要特别小心，最好定义位域常量。