📚 课程目录第4章 Linux MMIO核心API

4. Linux MMIO核心API：ioremap、ioremap_nocache、iounmap函数详解

在Linux驱动开发中，访问硬件设备的内存映射I/O（MMIO）区域是驱动与硬件交互的核心操作。MMIO将外设的寄存器、FIFO或控制状态内存直接映射到CPU的物理地址空间，驱动通过虚拟地址访问这些区域。Linux内核提供了一组核心API——ioremap、ioremap_nocache和iounmap——用于管理MMIO映射的生命周期。本章深入解析这三个函数的原型、行为差异、使用场景及底层机制。

4.1 MMIO映射的基本概念

在x86/ARM/ RISC-V等架构上，CPU通过内存总线访问外设寄存器。MMIO区域具有以下关键属性：

物理地址连续：外设寄存器在物理地址空间中是连续的一段。
不可缓存：对寄存器的读写必须直接到达硬件，不能经过CPU缓存，否则会导致数据不一致或时序错误。
访问顺序敏感：硬件寄存器通常要求严格的读写顺序，编译器或CPU不能重排。

内核提供ioremap系列函数将物理MMIO地址映射到内核虚拟地址空间，并设置页表属性为设备内存类型（Device memory），从而禁止缓存和重排序。

  关键理解： MMIO映射不是普通内存映射。普通内存使用ioremap会破坏缓存一致性，导致硬件行为异常。驱动必须始终使用ioremap系列API访问外设寄存器。

4.2 ioremap函数详解

ioremap是MMIO映射的主要入口，原型定义在<linux/io.h>中：

#include <linux/io.h>

void __iomem *ioremap(phys_addr_t offset, unsigned long size);

参数/返回值	说明
`offset`	MMIO区域的物理起始地址（如0xFE200000）
`size`	需要映射的字节长度
`返回值`	映射后的内核虚拟地址指针，类型为`void __iomem *`；失败返回`NULL`

使用步骤：

从设备树或PCI配置空间获取MMIO物理地址和长度。
调用ioremap建立映射。
通过readl()/writel()等访问函数操作寄存器。
在驱动卸载或模块移除时调用iounmap释放映射。

典型代码示例：

#include <linux/io.h>
#include <linux/module.h>

#define UART_BASE  0xFE200000
#define UART_SIZE  0x1000

static void __iomem *uart_regs;

static int __init my_driver_init(void)
{
    uart_regs = ioremap(UART_BASE, UART_SIZE);
    if (!uart_regs) {
        pr_err("Failed to ioremap UART registers\n");
        return -ENOMEM;
    }

    // 通过MMIO访问UART控制寄存器
    writel(0x01, uart_regs + 0x00);  // 使能UART
    pr_info("UART MMIO mapped at %p\n", uart_regs);
    return 0;
}

static void __exit my_driver_exit(void)
{
    if (uart_regs)
        iounmap(uart_regs);
}

module_init(my_driver_init);
module_exit(my_driver_exit);

提示： 返回值类型void __iomem *是内核的“稀疏”标记，用于静态检查工具（如Sparse）检测MMIO地址是否被错误地当作普通内存指针使用。不要直接解引用__iomem指针，必须使用readl/writel等访问函数。

4.3 ioremap_nocache函数详解

ioremap_nocache是ioremap的早期变体，在现代内核中其行为已被ioremap默认包含。原型如下：

void __iomem *ioremap_nocache(phys_addr_t offset, unsigned long size);

与ioremap的关系：

特性	ioremap	ioremap_nocache
缓存策略	默认不可缓存（Device memory）	强制不可缓存（强序）
写合并	架构相关，通常禁止	禁止写合并
重排序	禁止CPU/编译器重排	禁止CPU/编译器重排
内核版本	2.6+ 推荐使用	2.4及早期，现已被`ioremap`取代

实际建议： 在Linux 4.x及以后内核中，ioremap默认就是非缓存的，ioremap_nocache只是一个兼容宏。新驱动应直接使用ioremap。如果需要强序非缓存语义（如DMA描述符区域），使用ioremap_nocache可提高代码可读性，但功能等价。

警告： 不要使用ioremap_cache映射MMIO寄存器。缓存MMIO会导致寄存器写入延迟、读取值过时，严重时造成硬件死锁或数据损坏。只有帧缓冲等特殊场景才考虑缓存映射。

4.4 iounmap函数详解

当驱动不再需要访问MMIO区域时，必须调用iounmap释放映射，否则会造成虚拟地址泄漏。原型：

void iounmap(const volatile void __iomem *addr);

参数	说明
`addr`	由`ioremap`/`ioremap_nocache`返回的虚拟地址

调用规则：

必须在驱动退出或设备移除时调用。
传入的地址必须与ioremap返回值一致，不能传递偏移后的地址。
多次调用iounmap同一地址是未定义行为。
如果ioremap返回NULL，不要调用iounmap。

典型错误示例：

// 错误：使用偏移后的地址调用iounmap
void __iomem *regs = ioremap(0xFE200000, 0x1000);
void __iomem *ctrl = regs + 0x10;
iounmap(ctrl);  // 错误！应该传入regs

// 正确做法
iounmap(regs);

4.5 MMIO映射生命周期与访问流程

下图展示了从物理地址到虚拟地址的完整映射流程，以及驱动如何通过MMIO访问硬件寄存器：

4.6 访问函数与内存屏障

内核提供一组有序访问函数用于操作MMIO区域，这些函数内嵌了必要的内存屏障：

函数	操作	宽度	屏障语义
`readb()`	读8位	1字节	读屏障（保证之前所有读完成）
`readw()`	读16位	2字节	读屏障
`readl()`	读32位	4字节	读屏障
`readq()`	读64位	8字节	读屏障（仅64位架构）
`writeb()`	写8位	1字节	写屏障（保证之前所有写完成）
`writew()`	写16位	2字节	写屏障
`writel()`	写32位	4字节	写屏障
`writeq()`	写64位	8字节	写屏障（仅64位架构）

最佳实践： 始终使用readl/writel系列函数，不要使用memcpy_fromio/memcpy_toio访问单个寄存器。对于批量传输（如DMA描述符），使用memcpy_toio配合wmb()屏障。

4.7 常见错误与调试

MMIO映射错误是驱动开发中的常见问题，以下是典型错误场景及排查方法：

错误类型	现象	原因	解决方案
映射失败	`ioremap`返回`NULL`	物理地址无效、长度超出范围、权限不足	检查设备树/PCI资源，确认地址正确
寄存器写入无效	硬件无响应	使用了缓存映射或`ioremap_cache`	改用`ioremap`或`ioremap_nocache`
数据不一致	读取值始终为0或旧值	缺少内存屏障或使用了普通内存访问	使用`readl`/`writel`替代直接解引用
虚拟地址泄漏	内核内存占用持续增长	未调用`iounmap`	在退出路径添加`iounmap`
内核崩溃	Oops在MMIO访问处	映射地址错误或越界访问	验证`size`参数是否覆盖所有寄存器

调试技巧： 使用/proc/iomem查看系统已注册的物理地址范围，确认MMIO区域是否被其他驱动占用。使用devmem2工具（用户态）可临时验证物理地址是否可访问。

4.8 总结

ioremap、ioremap_nocache和iounmap是Linux驱动开发中MMIO映射的基石。核心要点：

ioremap：将物理MMIO地址映射到内核虚拟地址，默认非缓存、强序。
ioremap_nocache：与ioremap功能等价，用于兼容旧代码。
iounmap：释放映射，必须在驱动退出时调用。
访问函数：始终使用readl/writel系列，不要直接解引用__iomem指针。
内存屏障：MMIO访问函数内嵌屏障，保证读写顺序。