3. ioctl 命令编码规范

Linux 内核为 ioctl 命令定义了一套严格的编码规范，确保命令在全局范围内具有唯一性、可读性和可维护性。每个 ioctl 命令实际上是一个 32 位无符号整数，内核通过位域操作将其分解为四个组成部分：类型（Type）、编号（Number）、数据传输方向（Direction）和数据大小（Size）。

3.1 命令编码的组成结构

一个标准的 ioctl 命令编码由以下四个字段组成，总宽度为 32 位：

3.2 数据传输方向（Direction）

Direction 字段占用最高 2 位，定义了用户空间与内核空间之间的数据流动方向。内核预定义了四个方向常量：

3.3 类型（Type）与编号（Number）

Type（幻数）是一个 8 位的 ASCII 字符，用于标识命令所属的驱动或子系统。内核文档要求每个驱动选择一个唯一的字符作为幻数，避免与其他驱动冲突。例如：

• 'a' ~ 'z'：自定义驱动常用小写字母
• 'A' ~ 'Z'：部分内核子系统使用大写字母
• 0x00 ~ 0xFF：某些特殊场景使用数字

Number（编号）是 8 位的命令序号，在同一 Type 下从 0 开始顺序递增。建议按功能模块分组编号，例如：

/* 假设驱动幻数为 'M' */
#define MY_IOCTL_RESET       _IO('M', 0)    /* 复位设备 */
#define MY_IOCTL_GET_STATUS  _IOR('M', 1, int)   /* 获取状态 */
#define MY_IOCTL_SET_CONFIG  _IOW('M', 2, struct my_cfg) /* 设置配置 */
#define MY_IOCTL_EXCHANGE    _IOWR('M', 3, struct my_data) /* 交换数据 */

3.4 辅助宏：_IO / _IOR / _IOW / _IOWR

内核提供了四个辅助宏，用于简化 ioctl 命令的构造。这些宏定义在 <linux/ioctl.h> 中，开发者无需手动拼接位域：

这些宏的底层实现均调用 _IOC() 基础宏：

/* 内核源码 include/uapi/asm-generic/ioctl.h */
#define _IO(type, nr)        _IOC(_IOC_NONE, (type), (nr), 0)
#define _IOR(type, nr, size) _IOC(_IOC_READ, (type), (nr), sizeof(size))
#define _IOW(type, nr, size) _IOC(_IOC_WRITE, (type), (nr), sizeof(size))
#define _IOWR(type, nr, size) _IOC(_IOC_READ | _IOC_WRITE, (type), (nr), sizeof(size))

3.5 命令解码与校验

内核同样提供了一组解码宏，用于从命令编码中提取各个字段。这些宏在驱动实现中用于校验传入命令的合法性：

/* 解码宏定义 */
#define _IOC_DIR(nr)    (((nr) >> 30) & 0x03)   /* 提取方向 */
#define _IOC_TYPE(nr)   (((nr) >> 16) & 0xFF)   /* 提取类型 */
#define _IOC_NR(nr)     ((nr) & 0xFF)            /* 提取编号 */
#define _IOC_SIZE(nr)   (((nr) >> 8) & 0xFF)    /* 提取数据大小 */

/* 驱动中典型的命令校验模式 */
static long my_ioctl(struct file *filp, unsigned int cmd, unsigned long arg)
{
    /* 校验幻数 */
    if (_IOC_TYPE(cmd) != MY_MAGIC) {
        pr_err("ioctl: invalid magic number\n");
        return -ENOTTY;
    }

    /* 校验编号范围 */
    if (_IOC_NR(cmd) >= MY_IOCTL_MAXNR) {
        pr_err("ioctl: invalid command number\n");
        return -ENOTTY;
    }

    /* 校验数据大小（可选） */
    if (_IOC_SIZE(cmd) > sizeof(struct my_data)) {
        pr_err("ioctl: data size mismatch\n");
        return -EINVAL;
    }

    /* 根据命令分发处理 */
    switch (cmd) {
    case MY_IOCTL_RESET:
        /* ... */
        break;
    case MY_IOCTL_GET_STATUS:
        /* ... */
        break;
    default:
        return -ENOTTY;
    }
    return 0;
}

3.6 编码规范总结与避坑指南

以下是 ioctl 命令编码设计时需要遵守的核心规则和常见陷阱：