3、用户空间 mmap 系统调用：函数原型、参数详解与返回值

在嵌入式 Linux 驱动开发中，mmap 是用户空间与内核空间共享内存的核心系统调用。它允许用户程序将设备内存或内核缓冲区直接映射到进程的虚拟地址空间，从而避免昂贵的 read/write 数据拷贝，是实现高性能 DMA 传输的关键桥梁。本节将深入剖析 mmap 的函数原型、每个参数的含义、返回值及常见错误码。

3.1 mmap 函数原型

mmap 系统调用的原型定义在 <sys/mman.h> 头文件中，其标准签名如下：

#include <sys/mman.h>

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

该函数请求内核在调用进程的虚拟地址空间中创建一个新的内存映射。映射的源可以是文件描述符 fd 引用的文件或设备，也可以是匿名内存（flags 中指定 MAP_ANONYMOUS）。

3.2 参数详解

下表列出了 mmap 的六个参数及其详细说明：

3.2.1 prot 参数：内存保护标志

prot 参数可以是以下值的按位或组合：

• PROT_READ (0x1)：映射区域可读。
• PROT_WRITE (0x2)：映射区域可写。
• PROT_EXEC (0x4)：映射区域可执行（通常用于代码段映射）。
• PROT_NONE (0x0)：映射区域不可访问。访问该区域将触发 SIGSEGV 信号。

3.2.2 flags 参数：映射类型与行为

flags 参数是 mmap 最复杂的部分，它决定了映射的语义。常用标志如下：

3.3 返回值与错误码

mmap 的返回值提供了映射是否成功的明确指示：

• 成功： 返回映射区域的起始虚拟地址（void *）。该地址是页对齐的，用户程序可直接通过指针访问映射内容。
• 失败： 返回 MAP_FAILED（即 (void *) -1），并设置全局变量 errno 以指示具体错误原因。

下表列出了常见的 errno 错误码及其含义：

3.4 mmap 系统调用流程示意图

下图展示了用户空间调用 mmap 后，参数如何传递至内核，并最终通过 VFS 层到达设备驱动的 file_operations.mmap 回调的完整流程：

3.5 典型调用示例

以下代码片段展示了用户空间如何调用 mmap 映射一个 DMA 设备缓冲区：

#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <sys/mman.h>
#include <unistd.h>
#include <errno.h>

#define DMA_BUF_SIZE  (4 * 1024 * 1024)  /* 4 MB DMA 缓冲区 */

int main(void)
{
    int fd;
    void *map_base;
    off_t dev_offset = 0;  /* 从设备内存起始地址映射 */

    /* 1. 打开设备文件 */
    fd = open("/dev/dma_device", O_RDWR);
    if (fd < 0) {
        perror("open");
        exit(EXIT_FAILURE);
    }

    /* 2. 调用 mmap 建立映射 */
    map_base = mmap(NULL,                    /* 内核选择起始地址 */
                    DMA_BUF_SIZE,            /* 映射长度 */
                    PROT_READ | PROT_WRITE,  /* 读写权限 */
                    MAP_SHARED,              /* 共享映射，必须用于驱动 */
                    fd,                      /* 设备文件描述符 */
                    dev_offset);             /* 偏移量 */

    if (map_base == MAP_FAILED) {
        fprintf(stderr, "mmap failed, errno = %d\n", errno);
        close(fd);
        exit(EXIT_FAILURE);
    }

    /* 3. 直接通过指针访问 DMA 缓冲区 */
    printf("DMA buffer mapped at: %p\n", map_base);
    /* 例如：写入数据到缓冲区 */
    *(volatile unsigned int *)map_base = 0xA5A5A5A5;

    /* 4. 解除映射 */
    munmap(map_base, DMA_BUF_SIZE);
    close(fd);

    return 0;
}

3.6 参数对齐与页边界约束

内核要求 mmap 的 offset 和 length 必须遵循页对齐规则。下表总结了这些约束及其原因：