KMDF框架IOCTL与中断处理协同设计实战 - 第2节

2.1 IOCTL 概念与在 KMDF 中的角色

IOCTL（Input/Output Control）是 Windows 驱动模型中用于用户态应用与内核态驱动之间进行控制操作的核心机制。与常规的读写操作不同，IOCTL 专为设备特定的控制命令设计，例如配置设备参数、获取状态信息、执行硬件复位等。

2.1.1 IOCTL 与读写操作的本质区别

2.2 IRP 主功能码与 IOCTL 的关联

在 Windows I/O 模型中，每个 I/O 请求都被封装为 IRP（I/O Request Packet）。IRP 的主功能码（Major Function Code）标识请求的类型。IOCTL 请求对应的主功能码为 IRP_MJ_DEVICE_CONTROL（以及用于内部控制的 IRP_MJ_INTERNAL_DEVICE_CONTROL）。

2.2.1 与 IOCTL 相关的 IRP 主功能码

2.3 IOCTL 控制码定义规则

IOCTL 控制码是一个 32 位无符号整数，其内部按位域划分为 4 个组成部分。Windows 定义了严格的编码规则，确保不同设备、不同控制命令之间不会冲突。

2.3.1 控制码的位域结构

2.3.2 四个位域的详细定义

2.4 CTL_CODE 宏详解

CTL_CODE 是 Windows DDK/WDK 提供的预处理器宏，用于按照上述位域规则生成 IOCTL 控制码。该宏定义在 wdm.h 或 ntddk.h 中，是驱动开发者定义自定义 IOCTL 的标准工具。

2.4.1 CTL_CODE 宏原型

#define CTL_CODE(DeviceType, Function, Method, Access) \
    (((DeviceType) << 16) | ((Access) << 14) | ((Function) << 2) | (Method))

2.4.2 参数说明与常用取值

2.4.3 自定义 IOCTL 定义示例

// 设备类型：自定义未知设备
#define MY_DEVICE_TYPE FILE_DEVICE_UNKNOWN

// 功能码：从 0x800 开始避免冲突
#define IOCTL_GET_STATUS      CTL_CODE(MY_DEVICE_TYPE, 0x800, METHOD_BUFFERED, FILE_ANY_ACCESS)
#define IOCTL_SET_CONFIG      CTL_CODE(MY_DEVICE_TYPE, 0x801, METHOD_BUFFERED, FILE_WRITE_ACCESS)
#define IOCTL_RESET_DEVICE    CTL_CODE(MY_DEVICE_TYPE, 0x802, METHOD_BUFFERED, FILE_READ_ACCESS)
#define IOCTL_START_CAPTURE   CTL_CODE(MY_DEVICE_TYPE, 0x803, METHOD_IN_DIRECT, FILE_READ_ACCESS)
#define IOCTL_STOP_CAPTURE    CTL_CODE(MY_DEVICE_TYPE, 0x804, METHOD_OUT_DIRECT, FILE_WRITE_ACCESS)

2.4.4 四种缓冲区传递方式对比

2.5 KMDF 中 IOCTL 处理的典型流程

1. 用户态调用：应用调用 DeviceIoControl API，传入设备句柄、IOCTL 控制码、输入/输出缓冲区。
2. I/O 管理器构建 IRP：系统将请求封装为 IRP_MJ_DEVICE_CONTROL IRP，控制码存入 IrpSp->Parameters.DeviceIoControl.IoControlCode。
3. KMDF 框架路由：框架拦截 IRP，创建 WDFREQUEST 对象，调用驱动注册的 EvtIoDeviceControl 回调。
4. 驱动处理：驱动通过 WdfRequestGetParameters 获取控制码，使用 WdfRequestRetrieveInputBuffer / WdfRequestRetrieveOutputBuffer 访问数据。
5. 完成请求：驱动处理完毕后调用 WdfRequestComplete 返回状态和数据。

VOID
EvtIoDeviceControl(
    WDFQUEUE Queue,
    WDFREQUEST Request,
    size_t OutputBufferLength,
    size_t InputBufferLength,
    ULONG IoControlCode
    )
{
    NTSTATUS status = STATUS_SUCCESS;

    switch (IoControlCode)
    {
    case IOCTL_GET_STATUS:
        // 处理获取状态命令
        status = ProcessGetStatus(Request, OutputBufferLength);
        break;

    case IOCTL_SET_CONFIG:
        // 处理设置配置命令
        status = ProcessSetConfig(Request, InputBufferLength);
        break;

    case IOCTL_RESET_DEVICE:
        // 处理复位命令
        status = ProcessResetDevice(Request);
        break;

    default:
        status = STATUS_INVALID_DEVICE_REQUEST;
        break;
    }

    WdfRequestComplete(Request, status);
}

2.6 本章小结

• IOCTL 是用户态与内核态之间传递控制命令的标准机制，KMDF 通过 EvtIoDeviceControl 回调封装。
• IRP 主功能码 IRP_MJ_DEVICE_CONTROL 标识 IOCTL 请求，KMDF 自动完成 IRP 到 WDFREQUEST 的转换。
• IOCTL 控制码是 32 位整数，由 Device Type、Access、Function、Method 四个位域组成。
• CTL_CODE 宏是定义自定义 IOCTL 的标准工具，功能码必须使用 0x800~0xFFF 范围。
• 缓冲区传递方式推荐优先使用 METHOD_BUFFERED，兼顾安全性与兼容性。