4. 命令码编码规范：Linux内核ioctl命令码组成

Linux内核为ioctl命令码定义了一套严格的编码规范，将命令码分解为type（幻数）、nr（编号）、size（大小）和direction（方向）四个字段。这套规范保证了命令码的唯一性、可读性和跨平台兼容性。

4.1 命令码的32位分解结构

ioctl命令码是一个32位无符号整数，其内部布局如下表所示：

4.2 方向字段（direction）

方向字段定义数据传输的流向，内核根据该字段决定是否在用户态与内核态之间拷贝数据。方向值定义在 <linux/uaccess.h> 中：

4.3 四个核心构造宏

Linux内核提供四个宏来构造合法的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() 宏完成位域组装：

/* include/uapi/asm-generic/ioctl.h */
#define _IOC(dir, type, nr, size) \
    (((dir)  << _IOC_DIRSHIFT) | \
     ((type) << _IOC_TYPESHIFT) | \
     ((nr)   << _IOC_NRSHIFT) | \
     ((size) << _IOC_SIZESHIFT))

4.4 宏使用对比与选择策略

4.5 幻数（type）选择规范

幻数（type）是设备驱动的唯一标识符，通常使用一个ASCII字符。内核文档 Documentation/ioctl/ioctl-number.rst 记录了已分配的幻数：

4.6 完整命令码定义示例

以下是一个典型的字符设备驱动ioctl命令集定义：

/* my_device.h */
#ifndef MY_DEVICE_IOCTL_H
#define MY_DEVICE_IOCTL_H

#include <linux/ioctl.h>

/* 幻数：使用 'M' 作为设备标识 */
#define MY_DEV_MAGIC  'M'

/* 数据结构定义 */
struct my_dev_config {
    unsigned int   baud_rate;
    unsigned char  data_bits;
    unsigned char  parity;
    unsigned char  stop_bits;
};

struct my_dev_status {
    unsigned int   rx_bytes;
    unsigned int   tx_bytes;
    unsigned char  link_state;
    unsigned char  error_flags;
};

/* 无数据命令 */
#define MY_DEV_RESET        _IO(MY_DEV_MAGIC, 0)
#define MY_DEV_START        _IO(MY_DEV_MAGIC, 1)
#define MY_DEV_STOP         _IO(MY_DEV_MAGIC, 2)

/* 只读命令 */
#define MY_DEV_GET_STATUS   _IOR(MY_DEV_MAGIC, 3, struct my_dev_status)
#define MY_DEV_GET_VERSION  _IOR(MY_DEV_MAGIC, 4, unsigned int)

/* 只写命令 */
#define MY_DEV_SET_CONFIG   _IOW(MY_DEV_MAGIC, 5, struct my_dev_config)
#define MY_DEV_SET_BAUD     _IOW(MY_DEV_MAGIC, 6, unsigned int)

/* 读写命令 */
#define MY_DEV_EXCHANGE_CFG _IOWR(MY_DEV_MAGIC, 7, struct my_dev_config)

/* 校验宏：确保命令码不冲突 */
#define MY_DEV_IOCTL_MAXNR  8

#endif /* MY_DEVICE_IOCTL_H */

4.7 命令码生成与解析流程

下面的SVG图展示了从宏定义到最终命令码的完整生成流程，以及内核在接收命令后的解析路径：

4.8 内核提供的解析辅助宏

内核在 <linux/ioctl.h> 中提供了四个解析宏，用于从命令码中提取各个字段：

/* 提取方向字段 */
#define _IOC_DIR(cmd)       (((cmd) >> 30) & 0x03)

/* 提取幻数字段 */
#define _IOC_TYPE(cmd)      (((cmd) >> 8)  & 0xFF)

/* 提取编号字段 */
#define _IOC_NR(cmd)        ((cmd) & 0xFF)

/* 提取数据大小字段 */
#define _IOC_SIZE(cmd)      (((cmd) >> 16) & 0x3FFF)

4.9 常见错误与避坑指南

• 幻数冲突：使用已被占用的幻数（如 'a'、'v'）会导致与其他驱动命令码重叠，引发不可预知的行为。始终查阅 ioctl-number.rst。
• 方向设置错误：将只读命令错误地使用 _IOW 会导致内核尝试向用户空间写入数据，触发 copy_to_user 失败或数据损坏。
• size 字段溢出：数据结构大小超过 16383 字节（14位最大值）时，size 字段会被截断。此时需要将数据拆分为多个命令或使用指针间接传递。
• nr 编号重复：同一个驱动内不能有两个命令使用相同的 nr 值，否则 switch-case 无法区分。
• 手动拼接命令码：直接使用 #define MY_CMD 0x12345678 而不是宏定义，会导致内核无法正确解析字段，且无法通过编译时的类型检查。