📚 课程目录第4章 ioctl命令编码

4. ioctl命令编码

ioctl 接口的核心在于 命令码（cmd）。它不仅仅是一个简单的整数，而是一个经过精心编码的 32 位值，包含了操作类型、设备类型、数据方向、数据大小等关键信息。这种编码机制使得内核能够对 ioctl 请求进行严格的校验，防止非法或错误的操作。

4.1 命令码的组成结构

Linux 内核将 ioctl 命令码定义为一个 unsigned int（32 位），并将其划分为 4 个字段。这种结构化的设计是 Linux 驱动开发的标准实践。

命令码 32 位布局（从高位到低位）：

字段	位范围	宽度	宏定义	说明
direction	30-31	2 bits	`_IOC_DIRSHIFT=30`	数据传输方向：读、写、读写、无数据
type (magic)	8-15	8 bits	`_IOC_TYPESHIFT=8`	设备类型标识符（魔数），通常用 ASCII 字符
nr (number)	0-7	8 bits	`_IOC_NRSHIFT=0`	命令序号，同一设备类型下的不同命令
size	16-29	14 bits	`_IOC_SIZESHIFT=16`	用户态与内核态传输的数据大小（字节）

设计思想： 这种编码方式使得内核可以在不调用具体驱动处理函数之前，通过 _IOC_TYPE、_IOC_NR、_IOC_DIR 和 _IOC_SIZE 宏快速验证命令的合法性，避免错误命令导致内核崩溃。

4.2 数据传输方向（direction）

direction 字段定义了用户态与内核态之间的数据流动方向。内核根据此字段决定如何拷贝数据以及是否允许该操作。

方向宏	值	含义	典型场景
`_IOC_NONE`	0	无数据传输	仅控制操作，如设备复位、使能
`_IOC_READ`	2	从内核读取数据到用户态	获取设备状态、读取寄存器值
`_IOC_WRITE`	4	从用户态写入数据到内核	设置设备参数、下发配置
`_IOC_READ \| _IOC_WRITE`	6	双向数据传输	先下发请求，再读取结果

注意： 方向定义是从 用户态视角 出发的。例如 _IOC_READ 表示用户态从内核读取数据，即内核向用户态写入数据。初学者容易混淆，务必牢记。

4.3 构造命令码的四大宏

Linux 内核在 <linux/ioctl.h> 中提供了四个标准宏，用于方便地构造 ioctl 命令码。这些宏是驱动开发者的必备工具。

// 无数据传递的命令
#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))

这些宏最终都调用底层的 _IOC() 宏来组装最终的 32 位命令码：

#define _IOC(dir, type, nr, size) \
    (((dir)  << _IOC_DIRSHIFT)  | \
     ((type) << _IOC_TYPESHIFT) | \
     ((nr)   << _IOC_NRSHIFT)   | \
     ((size) << _IOC_SIZESHIFT))

4.4 宏的使用规范与示例

在实际驱动开发中，需要为每个设备定义一个唯一的 type（魔数），并在头文件中声明所有命令。

典型驱动头文件示例：

/* mydevice.h */
#ifndef MYDEVICE_IOCTL_H
#define MYDEVICE_IOCTL_H

#include <linux/ioctl.h>

/* 设备魔数：选择一个未被占用的 ASCII 字符 */
#define MYDEVICE_MAGIC  'M'

/* 命令序号定义 */
#define MYDEVICE_RESET      _IO(MYDEVICE_MAGIC, 0)      /* 复位设备，无数据 */
#define MYDEVICE_GET_STATUS _IOR(MYDEVICE_MAGIC, 1, int) /* 读取状态，返回 int */
#define MYDEVICE_SET_CONFIG _IOW(MYDEVICE_MAGIC, 2, struct myconfig) /* 设置配置 */
#define MYDEVICE_EXCHANGE   _IOWR(MYDEVICE_MAGIC, 3, struct mydata)  /* 交换数据 */

/* 确保命令序号不冲突 */
#define MYDEVICE_CMD_MAX    4

/* 用户态数据结构 */
struct myconfig {
    unsigned int baud_rate;
    unsigned char parity;
};

struct mydata {
    unsigned int input;
    unsigned int output;
};

#endif /* MYDEVICE_IOCTL_H */

4.5 命令码的校验与解码

内核提供了配套的解码宏，用于从命令码中提取各个字段。这些宏在驱动实现的 switch-case 中非常有用。

解码宏	返回值	用途
`_IOC_DIR(cmd)`	方向值	检查数据传输方向
`_IOC_TYPE(cmd)`	魔数字节	验证设备类型是否匹配
`_IOC_NR(cmd)`	命令序号	定位具体命令处理分支
`_IOC_SIZE(cmd)`	数据大小	检查缓冲区大小是否足够

/* 内核驱动中的典型校验流程 */
static long mydevice_ioctl(struct file *filp, unsigned int cmd, unsigned long arg)
{
    int ret = 0;

    /* 1. 检查魔数 */
    if (_IOC_TYPE(cmd) != MYDEVICE_MAGIC) {
        pr_err("ioctl: invalid magic number\n");
        return -ENOTTY;
    }

    /* 2. 检查命令序号范围 */
    if (_IOC_NR(cmd) >= MYDEVICE_CMD_MAX) {
        pr_err("ioctl: invalid command number\n");
        return -ENOTTY;
    }

    /* 3. 检查数据方向（可选，但推荐） */
    if (_IOC_DIR(cmd) & _IOC_READ) {
        /* 确保用户态缓冲区可写 */
    }

    /* 4. 根据命令序号分发处理 */
    switch (cmd) {
    case MYDEVICE_RESET:
        /* 处理复位 */
        break;
    case MYDEVICE_GET_STATUS:
        /* 处理读取状态 */
        break;
    case MYDEVICE_SET_CONFIG:
        /* 处理设置配置 */
        break;
    default:
        return -ENOTTY;
    }

    return ret;
}

4.6 常见错误与避坑指南

魔数冲突： 多个驱动使用相同的魔数会导致命令码冲突。建议查阅 Documentation/ioctl/ioctl-number.rst 选择未被占用的字符。
size 字段溢出： size 字段只有 14 位，最大表示 16383 字节。传输大数据结构时需注意，超过此限制应使用指针传递或分段传输。
方向误用： 使用 _IOR 但实际执行了写操作，或反之，会导致内核 copy_to_user/copy_from_user 方向错误，引发内核崩溃。
32/64 位兼容性： 用户态与内核态的数据结构大小可能因对齐方式不同而不同。建议使用固定宽度的整数类型（如 __u32）并显式指定对齐。

最佳实践： 始终在驱动头文件中使用 _IO/_IOR/_IOW/_IOWR 宏定义命令，不要手动拼接命令码。这不仅能保证正确性，还能提高代码的可读性和可维护性。

4.7 命令码生成流程总结

下面的 SVG 图展示了从宏定义到最终命令码生成的完整流程：

通过本章的学习，你应该能够理解 ioctl 命令码的编码原理，熟练使用 _IO/_IOR/_IOW/_IOWR 宏定义命令，并在驱动开发中正确进行命令校验。这是实现安全、可靠的 ioctl 接口的基础。