📚 课程目录第2章 ioctl系统调用原型

2. ioctl 系统调用原型：用户空间接口详解

在嵌入式 Linux 驱动开发中，ioctl 是用户空间与内核驱动之间进行控制类通信的核心系统调用。与 read/write 的纯数据流不同，ioctl 专为“命令-参数”模式设计，允许应用程序向设备发送自定义控制指令并携带任意类型的参数。

核心认知： ioctl 的本质是一个“多路复用”系统调用——通过一个文件描述符 + 一个命令码，就能调用驱动中数十种不同的设备控制逻辑。理解其用户空间原型是掌握驱动命令封装的第一步。

2.1 用户空间 ioctl 函数原型

在 Linux 用户空间，ioctl 系统调用的函数原型定义在 <sys/ioctl.h> 头文件中：

#include <sys/ioctl.h>

int ioctl(int fd, unsigned long request, ...);

该函数是一个可变参数函数，第三个参数 ... 表示可以传递任意类型的参数（通常是一个指针）。这种设计使得 ioctl 能够灵活地传递结构体、整数、缓冲区地址等不同数据类型。

2.2 参数详解

参数	类型	方向	说明
fd	`int`	输入	通过 `open()` 获得的设备文件描述符，标识要操作的目标设备
request	`unsigned long`	输入	设备驱动定义的命令码，编码了命令类型、读写方向、数据大小等信息
arg	`...` (可变)	双向	可选的伴随参数，通常为指针类型，用于传递数据或接收内核返回信息

常见误区： 虽然原型中第三个参数是可变参数，但在实际使用中，绝大多数 ioctl 调用都只传递一个参数（即 arg）。如果省略该参数，内核驱动收到的 arg 值为未定义，极易导致内核崩溃。建议始终显式传递 0 或 NULL 作为占位。

2.3 参数详细分析

2.3.1 fd —— 设备文件描述符

fd 是用户空间与内核设备之间的通信通道。它必须通过 open() 系统调用获得，且该设备必须支持 ioctl 操作（即驱动中实现了 unlocked_ioctl 或 compat_ioctl 方法）。

int fd = open("/dev/mydevice", O_RDWR);
if (fd < 0) {
    perror("open");
    return -1;
}
// 使用 fd 进行 ioctl 操作
ioctl(fd, MY_CMD_GET_STATUS, &status);
close(fd);

2.3.2 request —— 命令码

request 是 ioctl 的灵魂参数。它是一个 32 位无符号整数，但并非随意取值，而是按照 Linux 内核规范进行编码。命令码的每一位都携带了特定信息：

类型（Type/Magic Number）：8 位，用于区分不同设备驱动，避免命令冲突
序号（Number）：8 位，同一设备驱动内的命令编号
方向（Direction）：2 位，指示数据流向（读/写/读写/无数据）
数据大小（Size）：14 位，伴随参数的数据长度（字节数）

  编码宏： 内核提供了 _IO()、_IOR()、_IOW()、_IOWR() 四个宏来生成标准命令码，驱动开发者不应手动拼装。

2.3.3 arg —— 伴随参数

arg 是 ioctl 的数据载体。根据命令码中编码的“方向”信息，arg 可以用于：

方向	宏	arg 用途	典型示例
无数据	`_IO()`	不使用 arg，通常传 0	设备复位、启动/停止
读（从设备读）	`_IOR()`	指向用户缓冲区的指针，内核向该缓冲区写入数据	读取设备状态、获取配置
写（向设备写）	`_IOW()`	指向用户缓冲区的指针，内核从该缓冲区读取数据	设置参数、下发配置
读写	`_IOWR()`	指向用户缓冲区的指针，内核先读后写	交换数据、原子操作

2.4 ioctl 调用流程与数据路径

下图展示了用户空间 ioctl() 调用如何通过系统调用进入内核，最终到达驱动程序的完整路径：

2.5 返回值与错误码

ioctl 系统调用的返回值提供了操作结果信息：

返回 0：操作成功（对于无数据返回的命令）
返回正数：操作成功，返回值为驱动定义的成功状态或数据量
返回 -1：操作失败，具体错误码通过 errno 全局变量获取

errno 值	宏定义	含义	常见原因
22	`EINVAL`	无效参数	request 命令码不被驱动识别，或 arg 参数非法
25	`ENOTTY`	设备不支持 ioctl 操作	文件描述符对应的设备没有实现 ioctl 方法
14	`EFAULT`	地址访问错误	arg 指针指向非法用户空间地址
16	`EBUSY`	设备忙	设备正在执行其他操作，无法响应当前命令
5	`EIO`	I/O 错误	硬件通信失败或设备未就绪

  编程建议： 用户空间代码应始终检查 ioctl 返回值，并使用 perror() 或 strerror(errno) 输出错误信息，便于调试驱动接口问题。

2.6 用户空间调用示例

以下是一个完整的用户空间 ioctl 调用示例，演示了如何向设备发送命令并传递结构体参数：

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

/* 假设驱动定义的命令码 */
#define MY_DEVICE_MAGIC   'M'
#define MY_CMD_GET_INFO   _IOR(MY_DEVICE_MAGIC, 1, struct device_info)
#define MY_CMD_SET_CONFIG _IOW(MY_DEVICE_MAGIC, 2, struct device_config)

struct device_info {
    unsigned int version;
    unsigned int status;
    char serial[32];
};

struct device_config {
    unsigned int baudrate;
    unsigned int timeout_ms;
    unsigned char mode;
};

int main(void)
{
    int fd;
    struct device_info info;
    struct device_config cfg = {
        .baudrate   = 115200,
        .timeout_ms = 1000,
        .mode       = 0x01
    };

    /* 打开设备 */
    fd = open("/dev/mydevice", O_RDWR);
    if (fd < 0) {
        perror("open");
        return -1;
    }

    /* 发送配置命令（写方向） */
    if (ioctl(fd, MY_CMD_SET_CONFIG, &cfg) < 0) {
        perror("ioctl set config");
        close(fd);
        return -1;
    }

    /* 读取设备信息（读方向） */
    if (ioctl(fd, MY_CMD_GET_INFO, &info) < 0) {
        perror("ioctl get info");
        close(fd);
        return -1;
    }

    printf("Device version: %u\n", info.version);
    printf("Device status:  %u\n", info.status);
    printf("Serial number:  %s\n", info.serial);

    close(fd);
    return 0;
}

2.7 参数传递的底层机制

理解 ioctl 参数在用户空间与内核空间之间的传递机制，对于正确使用该接口至关重要：

安全红线： 用户空间传递给内核的指针（arg）指向的是用户空间虚拟地址。内核驱动中绝对不能直接解引用该指针，必须使用 copy_from_user() 和 copy_to_user() 系列函数进行安全的数据拷贝。直接访问用户指针会导致内核崩溃或安全漏洞。

2.8 本章小结

ioctl 原型：int ioctl(int fd, unsigned long request, ...)，三个核心参数分别标识设备、命令和数据
fd：通过 open() 获得的设备通道，是用户空间与内核通信的桥梁
request：32 位命令码，编码了类型、序号、方向和数据大小，由内核宏生成
arg：可变参数，通常为指针，用于传递结构体、整数或缓冲区
返回值：0 或正数表示成功，-1 表示失败，通过 errno 获取具体错误码
安全机制：用户空间指针不能在内核中直接解引用，必须使用 copy_from_user/copy_to_user