4. 自定义 ioctl 命令定义：宏定义、编号分配与冲突避免

ioctl 接口的核心在于 命令编号（command number）。一个设计良好的命令编号不仅能够唯一标识操作，还能携带类型、序号、数据方向和数据大小等信息，从而在驱动与应用程序之间建立严格的契约。本章将深入讲解如何使用 Linux 内核提供的宏定义来构造自定义命令，并给出命令编号的分配原则与冲突避免策略。

4.1 命令编号的组成结构

Linux 内核将 ioctl 命令编号编码为一个 32 位整数，其内部划分为四个字段，每个字段承载特定的语义。理解这一结构是正确使用宏定义的前提。

4.2 使用宏定义构造命令

Linux 内核在 <linux/ioctl.h> 中提供了四个核心宏，用于生成标准化的命令编号。开发者不应手动拼接位域，而应始终使用这些宏。

4.2.1 典型定义示例

以下代码展示了一个字符设备驱动中自定义 ioctl 命令的完整定义过程：

/* mydevice.h — 用户空间与内核空间共享的头文件 */
#ifndef MYDEVICE_IOCTL_H
#define MYDEVICE_IOCTL_H

#include <linux/ioctl.h>   /* 内核空间 */
/* #include <sys/ioctl.h> */ /* 用户空间 */

/* 1. 选择魔数：使用一个 ASCII 字符，避免与已知子系统冲突 */
#define MYDEV_MAGIC  'M'

/* 2. 定义数据结构 */
struct mydev_data {
    unsigned int  reg_addr;
    unsigned int  reg_value;
};

/* 3. 定义命令编号 */
#define MYDEV_CMD_RESET      _IO(MYDEV_MAGIC, 0x01)
#define MYDEV_CMD_GET_STATUS _IOR(MYDEV_MAGIC, 0x02, struct mydev_data)
#define MYDEV_CMD_SET_CONFIG _IOW(MYDEV_MAGIC, 0x03, struct mydev_data)
#define MYDEV_CMD_RW_REG     _IOWR(MYDEV_MAGIC, 0x04, struct mydev_data)

/* 4. 验证魔数唯一性（可选，编译时检查） */
#define MYDEV_IOC_MAXNR      0x05

#endif /* MYDEVICE_IOCTL_H */

4.3 命令编号分配原则

合理的编号分配能够降低维护成本，避免驱动间的意外冲突。以下是经过大量生产项目验证的分配原则：

• 魔数唯一性原则：每个驱动或子系统使用一个唯一的 ASCII 字符作为魔数。内核文档 Documentation/ioctl/ioctl-number.rst 记录了已分配的魔数，新驱动应从中选择一个未被占用的字符。
• 序号递增原则：同一驱动内的命令序号从 0x00 开始连续递增，避免跳跃式分配导致后续维护混乱。
• 方向匹配原则：根据操作的实际数据流向选择正确的宏（_IO / _IOR / _IOW / _IOWR），不要为了省事而全部使用 _IOWR。
• 大小固定原则：同一个命令对应的数据结构大小必须固定，不能在同一命令中传递不同大小的结构体。
• 序号上限原则：为每个魔数保留一个最大序号值（如 MYDEV_IOC_MAXNR），在驱动入口处使用 _IOC_NR(cmd) > max_nr 进行越界检查。

4.4 避免命令冲突的策略

命令冲突会导致驱动行为异常，甚至系统崩溃。以下策略可以有效降低冲突风险：

4.5 编译时验证与运行时检查

为了在开发早期捕获命令编号错误，建议在驱动初始化函数中加入编译时和运行时检查：

/* 驱动入口文件 mydevice.c */
#include <linux/ioctl.h>
#include <linux/bug.h>   /* 用于 BUILD_BUG_ON */

static int __init mydev_init(void)
{
    /* 编译时检查：确保魔数未被内核占用 */
    BUILD_BUG_ON(MYDEV_MAGIC == 0);
    BUILD_BUG_ON(MYDEV_MAGIC > 0xFF);

    /* 编译时检查：确保序号不越界 */
    BUILD_BUG_ON(MYDEV_IOC_MAXNR > 0xFF);

    /* 运行时检查：注册 misc 或 char 设备 */
    /* ... */

    return 0;
}

/* ioctl 实现中的命令有效性检查 */
static long mydev_ioctl(struct file *filp, unsigned int cmd, unsigned long arg)
{
    /* 检查魔数 */
    if (_IOC_TYPE(cmd) != MYDEV_MAGIC) {
        pr_err("ioctl: invalid magic number 0x%02x\n", _IOC_TYPE(cmd));
        return -ENOTTY;
    }

    /* 检查序号范围 */
    if (_IOC_NR(cmd) > MYDEV_IOC_MAXNR) {
        pr_err("ioctl: invalid command number 0x%02x\n", _IOC_NR(cmd));
        return -ENOTTY;
    }

    /* 检查数据大小（可选） */
    if (_IOC_SIZE(cmd) != sizeof(struct mydev_data)) {
        pr_err("ioctl: size mismatch %zu vs %zu\n",
               _IOC_SIZE(cmd), sizeof(struct mydev_data));
        return -ENOTTY;
    }

    /* 分发命令 */
    switch (cmd) {
    case MYDEV_CMD_RESET:
        /* ... */
        break;
    case MYDEV_CMD_GET_STATUS:
        /* ... */
        break;
    /* ... */
    default:
        return -ENOTTY;
    }
    return 0;
}

4.6 魔数分配参考表

以下列出部分内核已分配的魔数，新驱动应避免使用这些字符：