2. ioctl系统调用原型：用户空间ioctl函数原型、参数详解

在Linux系统中，用户空间应用程序与内核驱动之间的通信，除了传统的read/write接口外，ioctl（Input/Output Control）提供了最为灵活的控制通道。它允许应用程序向设备发送任意类型的控制命令，并携带自定义参数。理解ioctl在用户空间的函数原型及其三个核心参数，是编写驱动控制逻辑的第一步。

2.1 用户空间ioctl函数原型

用户空间程序通过C标准库（glibc）提供的封装函数来发起ioctl系统调用。其原型定义在头文件<sys/ioctl.h>中：

#include <sys/ioctl.h>

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

2.2 参数详解：fd、request、arg

三个参数分别承担了“操作对象”、“操作命令”和“操作数据”的角色。下表详细说明了每个参数的类型、来源及用途：

2.3 参数深度解析

2.3.1 fd：文件描述符

fd是用户空间与内核设备之间的桥梁。它必须是通过open()成功打开的设备节点返回的有效描述符。如果fd无效（例如未打开或已被关闭），ioctl调用将返回-EBADF（Bad file descriptor）。

2.3.2 request：命令码

request是ioctl的核心。它不仅仅是一个简单的整数，而是一个编码了魔数、序号、数据传输方向和参数大小的复合码。Linux内核提供了四个宏来构造这个命令码：

• _IO(type, nr)：构造一个无数据传输的命令码。
• _IOR(type, nr, datatype)：构造一个从内核读取数据的命令码。
• _IOW(type, nr, datatype)：构造一个向内核写入数据的命令码。
• _IOWR(type, nr, datatype)：构造一个双向数据传输的命令码。

2.3.3 arg：可变参数

arg是ioctl灵活性的体现。根据request命令码的编码，内核驱动会以不同的方式解释arg：

• 整型值：当命令仅需一个简单的配置值时，arg可以直接传递一个unsigned long整数。
• 指针：当需要交换复杂数据结构时，arg必须是一个指向用户空间缓冲区的指针。内核驱动通过copy_from_user()和copy_to_user()安全地访问该缓冲区。
• NULL：如果命令不需要额外数据，arg可以传递0或NULL。

2.4 ioctl系统调用流程SVG图

下图展示了用户空间ioctl()调用如何通过系统调用进入内核，并最终到达驱动注册的unlocked_ioctl函数的过程：

2.5 参数传递与数据流向

理解arg参数在用户空间和内核空间之间的数据流向至关重要。下图展示了三种典型的数据传输模式：

2.6 常见错误与返回值

ioctl()系统调用在成功时通常返回0，但某些命令可能返回正数（如读取的字节数）。失败时返回-1，并设置全局变量errno。以下是驱动开发中常见的错误码：

2.7 用户空间调用示例

以下是一个典型的用户空间ioctl调用代码片段，展示了如何构造命令码并传递参数：

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

/* 假设驱动头文件中定义了以下命令码 */
#define MY_DEVICE_MAGIC   'k'
#define MY_CMD_GET_STATUS _IOR(MY_DEVICE_MAGIC, 1, int)
#define MY_CMD_SET_VALUE  _IOW(MY_DEVICE_MAGIC, 2, int)

int main(void) {
    int fd;
    int status;
    int value = 42;

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

    /* 2. 发送写命令：设置值 */
    if (ioctl(fd, MY_CMD_SET_VALUE, &value) == -1) {
        perror("ioctl set value");
        close(fd);
        exit(EXIT_FAILURE);
    }
    printf("Set value to %d\n", value);

    /* 3. 发送读命令：获取状态 */
    if (ioctl(fd, MY_CMD_GET_STATUS, &status) == -1) {
        perror("ioctl get status");
        close(fd);
        exit(EXIT_FAILURE);
    }
    printf("Device status: %d\n", status);

    /* 4. 关闭设备 */
    close(fd);
    return 0;
}