3. mmap 系统调用 API 详解

mmap 是 Linux 系统中最核心的内存映射接口，它允许用户态程序将文件或设备内存直接映射到进程的虚拟地址空间。本章将深入解析其原型、每个参数的含义、返回值处理以及常见错误码，帮助你在工程实践中准确使用这一系统调用。

3.1 函数原型与参数全景

mmap 的函数原型定义在 <sys/mman.h> 中，其完整签名如下：

#include <sys/mman.h>

void *mmap(void *addr, size_t length, int prot, int flags, int fd, off_t offset);

该函数接受 6 个参数，每个参数都直接影响映射的行为和安全性。下表总结了每个参数的作用与典型取值：

3.2 参数逐项深度解析

3.2.1 addr —— 映射地址提示

addr 参数用于向内核建议映射的虚拟起始地址。内核并不保证一定使用该地址，除非同时指定了 MAP_FIXED 标志。工程实践中的最佳做法是：

• 传 NULL：让内核自动选择合适的地址，兼容性最好，避免地址冲突。
• 非 NULL + 无 MAP_FIXED：内核将 addr 视为提示，可能调整到附近可用区域。
• 非 NULL + MAP_FIXED：强制内核在精确地址映射，若地址已被占用则失败（返回 MAP_FAILED）。

3.2.2 length —— 映射长度

length 指定映射的字节数。内核以页为单位管理内存，因此实际映射区域会向上取整到页大小的整数倍。例如，若页大小为 4096 字节，length = 5000 时实际映射 8192 字节。

关键约束：

• length 必须大于 0。
• 对于文件映射，length 可以超过文件大小，超出部分填充为 0（零页）。
• 访问超出 length 但仍在页对齐范围内的地址，行为未定义。

3.2.3 prot —— 保护标志

prot 参数控制映射区域的内存保护属性，可以是以下值的按位或组合：

在驱动映射场景中，最常用的组合是 PROT_READ | PROT_WRITE，用于读写设备内存或 DMA 缓冲区。如果设备内存需要执行代码（如固件加载），则需额外添加 PROT_EXEC。

3.2.4 flags —— 映射类型与行为

flags 是 mmap 最复杂的参数，它决定了映射的共享属性、内存来源和特殊行为。核心标志包括：

3.2.5 fd —— 文件描述符

fd 是已打开的文件或设备文件的描述符。对于匿名映射（MAP_ANONYMOUS），fd 应设为 -1，某些系统也接受 /dev/zero 的 fd。

在驱动映射中，fd 通常来自：

• open("/dev/mydevice", O_RDWR) 返回的字符设备 fd。
• shm_open() 返回的 POSIX 共享内存 fd。
• memfd_create() 创建的匿名文件 fd。

3.2.6 offset —— 文件偏移量

offset 指定文件映射的起始位置。对于设备驱动，offset 通常用于选择设备内部的物理内存区域或寄存器页。关键约束：

• 必须页对齐：offset 必须是系统页大小（sysconf(_SC_PAGE_SIZE)，通常 4096）的整数倍。
• 驱动中，offset 被传递给 file_operations.mmap 回调的 vma->vm_pgoff 字段，用于区分不同的映射区域。

3.3 返回值处理

mmap 的返回值是映射区域的起始虚拟地址，失败时返回 MAP_FAILED（即 (void *) -1）。正确的返回值检查模式如下：

void *mapped_addr = mmap(NULL, 4096, PROT_READ | PROT_WRITE,
                         MAP_SHARED, fd, 0);
if (mapped_addr == MAP_FAILED) {
    perror("mmap failed");
    exit(EXIT_FAILURE);
}
// 使用 mapped_addr ...
// 使用完毕后调用 munmap
if (munmap(mapped_addr, 4096) == -1) {
    perror("munmap failed");
}

3.4 错误码详解

当 mmap 失败时，errno 被设置为以下错误码之一。理解这些错误码对于调试驱动映射问题至关重要：

3.5 mmap 调用流程与内核交互

下图展示了用户态调用 mmap 后，系统调用进入内核，经过 VMA 管理、文件映射回调，最终返回用户态地址的完整流程：

3.6 参数组合与典型场景

不同的参数组合适用于不同的工程场景。下表总结了最常见的组合及其用途：

3.7 工程实践检查清单

在编写使用 mmap 的代码时，建议逐项检查以下要点：

1. 参数校验：length 是否大于 0？offset 是否页对齐？
2. 权限匹配：prot 中的读写标志是否与 open() 时的文件访问模式一致？
3. 共享属性：设备映射是否使用了 MAP_SHARED？
4. 返回值检查：是否使用 MAP_FAILED 而非 NULL 判断失败？
5. 错误码分析：失败时是否打印 errno 对应的错误信息？
6. 资源释放：是否在适当时机调用 munmap() 解除映射？
7. 驱动支持：设备驱动是否实现了 .mmap 回调？