3. Linux内核宏定义详解（上）：_IO、_IOR、_IOW、_IOWR宏的源码分析与使用场景

在Linux驱动开发中，ioctl命令号的编码是驱动与用户空间通信的基石。内核提供了四个核心宏——_IO、_IOR、_IOW、_IOWR——用于构造标准化的命令号。本章将深入分析这些宏的源码实现、位域布局，并结合实际场景说明其使用规范。

3.1 命令号编码的位域结构

一个标准的ioctl命令号是一个32位无符号整数，内核将其划分为四个位域，用于携带类型、序号、数据传输方向和参数大小等信息。理解位域结构是掌握宏定义的前提。

ioctl 命令号位域说明

位域	位范围	宽度	说明
dir	30-31	2 bits	数据传输方向：_IOC_NONE、_IOC_READ、_IOC_WRITE、_IOC_READ|_IOC_WRITE
type	8-15	8 bits	幻数/魔数，用于区分不同驱动或设备类，通常选用一个ASCII字符
nr	0-7	8 bits	序号，同一驱动内命令的编号，从0开始递增
size	16-29	14 bits	用户态与内核态交换的数据结构大小（字节数），由宏自动计算

3.2 核心宏源码分析

四个宏定义位于内核头文件 include/uapi/asm-generic/ioctl.h 中。它们通过组合位域操作，生成唯一的命令号。

3.2.1 基础辅助宏

/* 方向常量定义 */
#define _IOC_NONE       0U
#define _IOC_WRITE      1U
#define _IOC_READ       2U

/* 位域偏移与掩码 */
#define _IOC_NRBITS     8
#define _IOC_TYPEBITS   8
#define _IOC_SIZEBITS   14
#define _IOC_DIRBITS    2

#define _IOC_NRMASK     ((1 << _IOC_NRBITS) - 1)
#define _IOC_TYPEMASK   ((1 << _IOC_TYPEBITS) - 1)
#define _IOC_SIZEMASK   ((1 << _IOC_SIZEBITS) - 1)
#define _IOC_DIRMASK    ((1 << _IOC_DIRBITS) - 1)

#define _IOC_NRSHIFT    0
#define _IOC_TYPESHIFT  (_IOC_NRSHIFT + _IOC_NRBITS)
#define _IOC_SIZESHIFT  (_IOC_TYPESHIFT + _IOC_TYPEBITS)
#define _IOC_DIRSHIFT   (_IOC_SIZESHIFT + _IOC_SIZEBITS)

3.2.2 核心构造宏

/* 通用构造宏：手动指定方向 */
#define _IOC(dir, type, nr, size) \
    (((dir)  << _IOC_DIRSHIFT)  | \
     ((type) << _IOC_TYPESHIFT) | \
     ((nr)   << _IOC_NRSHIFT)   | \
     ((size) << _IOC_SIZESHIFT))

/* 无数据传输 */
#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.3 宏使用场景与规范

选择哪个宏取决于驱动与用户空间之间的数据流动方向。错误的方向声明可能导致权限检查失败或数据拷贝异常。

宏选择对照表

宏	方向	典型场景	示例
_IO	无数据	仅触发操作，如设备复位、状态查询（无参数）	_IO('M', 0)
_IOR	读	读取设备状态、获取配置参数	_IOR('M', 1, struct my_data)
_IOW	写	设置设备参数、下发命令	_IOW('M', 2, struct my_cfg)
_IOWR	双向	先写入请求再读取结果，如查询+应答	_IOWR('M', 3, struct my_req)

3.3.1 幻数（type）选择规范

幻数用于防止不同驱动之间的命令号冲突。内核社区推荐使用一个ASCII字符作为幻数，并尽量在 Documentation/ioctl/ioctl-number.rst 中注册，避免重复。

• 推荐做法：选用一个未被使用的字母或数字字符，如 'a'、'k'、'M'。
• 避免做法：使用 0 或 0xff 等特殊值，这些可能被内核保留。
• 注意：同一个驱动内的所有命令必须使用相同的幻数。

3.3.2 序号（nr）分配规范

序号从0开始递增，同一驱动内不能重复。通常按功能模块或版本顺序排列。

/* 某字符设备驱动命令定义示例 */
#define MY_IOCTL_BASE   'M'

#define MY_IOCTL_RESET      _IO(MY_IOCTL_BASE, 0)      /* 复位设备 */
#define MY_IOCTL_GET_STAT   _IOR(MY_IOCTL_BASE, 1, struct stat)  /* 获取状态 */
#define MY_IOCTL_SET_CFG    _IOW(MY_IOCTL_BASE, 2, struct cfg)   /* 设置配置 */
#define MY_IOCTL_EXCHANGE   _IOWR(MY_IOCTL_BASE, 3, struct msg)  /* 双向交换 */

3.4 常见错误与排查

3.5 宏展开实例验证

以下通过一个具体例子展示宏展开后的位运算结果，帮助理解命令号的生成过程。

/* 定义：幻数 'K' (0x4B)，序号 5，参数类型 struct msg */
#define MY_CMD  _IOWR('K', 5, struct msg)

/* 假设 sizeof(struct msg) = 64 (0x40) */
/* 展开过程：
 * dir  = _IOC_READ | _IOC_WRITE = 2 | 1 = 3 (0x3)
 * type = 'K' = 0x4B
 * nr   = 5
 * size = 64 = 0x40
 *
 * 最终命令号 = (3 << 30) | (0x4B << 8) | (5 << 0) | (0x40 << 16)
 *            = 0xC04B4005
 */

3.6 内核版本兼容性提示

不同内核版本对 _IOC_DIRBITS 的定义可能略有差异。在较老的内核（如2.4系列）中，方向位域可能只有1位，但现代内核（2.6+）统一使用2位。驱动开发时应以当前目标内核的 ioctl.h 为准。