4. ioctl 命令编码规范：_IO / _IOR / _IOW / _IOWR 宏定义

ioctl 命令码是用户空间与内核驱动之间传递“操作意图”的唯一标识。Linux 内核定义了一套严格的编码规范，将命令码拆分为 类型（Type）、序号（Number）、方向（Direction） 和 大小（Size） 四个字段，并通过 _IO、_IOR、_IOW、_IOWR 四个宏来生成标准命令码。

4.1 命令码的 32 位组成结构

一个标准的 ioctl 命令码是一个 32 位无符号整数，其位域划分如下：

4.2 方向（Direction）定义

方向字段占用最高 2 个 bit，决定数据在用户空间与内核空间之间的流动方式。内核头文件 <linux/ioctl.h> 中定义了以下方向常量：

4.3 四个核心构造宏

内核提供四个宏来生成标准命令码，开发者无需手动拼接位域：

这些宏在 <asm-generic/ioctl.h> 中的实现逻辑如下：

/* 内核源码：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))

其中 _IOC 是底层位拼接宏：

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

4.4 类型（Type）选择规范

类型字段（Magic Number）用于区分不同的设备驱动，防止命令码冲突。内核社区推荐以下规则：

• 使用 ASCII 字符：通常选择一个字母，如 'M'、'K'、'S'，便于阅读和调试。
• 避免与已有驱动冲突：查阅 Documentation/ioctl/ioctl-number.rst 确认所选字符未被占用。
• 自定义驱动建议：使用大写字母或数字组合，如 'a' 到 'z' 已被大量通用驱动使用，新驱动优先选择 'A' 到 'Z' 中未被分配的字符。

4.5 序号（Number）分配策略

序号字段在同一类型下唯一标识一个命令。推荐策略：

1. 从 0 开始递增：每个新命令分配下一个可用序号。
2. 预留范围：将 0-9 留给基础操作（如打开、关闭、复位），10-99 留给功能命令。
3. 避免跳过：不要随意跳过序号，除非为了兼容旧版本。
4. 文档化：在头文件中用注释标明每个序号的用途。

4.6 大小（Size）自动推导

大小字段由宏自动从 sizeof(datatype) 推导，开发者只需传入数据类型名称。注意：

• 数据类型必须是 固定大小 的结构体或基本类型，不能是变长数组或指针。
• 如果命令不需要传输数据（_IO），大小字段固定为 0。
• 内核在 copy_from_user / copy_to_user 时会校验大小是否匹配，不匹配返回 -EINVAL。

4.7 完整示例：自定义命令码定义

以下是一个字符设备驱动的命令码定义头文件：

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

#include <linux/ioctl.h>

/* 类型魔数：使用 'M' */
#define MYDEVICE_MAGIC 'M'

/* 数据结构 */
struct mydevice_status {
    int  temperature;
    int  humidity;
    char firmware_version[16];
};

struct mydevice_config {
    int  sample_rate;
    int  threshold;
};

/* 命令码定义 */
#define MYDEVICE_GET_STATUS   _IOR(MYDEVICE_MAGIC, 0, struct mydevice_status)
#define MYDEVICE_SET_CONFIG   _IOW(MYDEVICE_MAGIC, 1, struct mydevice_config)
#define MYDEVICE_RESET        _IO (MYDEVICE_MAGIC, 2)
#define MYDEVICE_EXCHANGE     _IOWR(MYDEVICE_MAGIC, 3, struct mydevice_status)

/* 检查命令码是否有效 */
#define MYDEVICE_IOCTL_MAXNR 3

#endif /* MYDEVICE_IOCTL_H */

4.8 命令码解码与调试

在调试时，可以使用内核提供的辅助宏反向解析命令码：

用户空间可以通过 ioctl_list 工具或 strace 查看实际传递的命令码值，辅助验证编码是否正确。