简介Sensy是一份面向嵌入式与Windows驱动开发学习者的教育型项目源码包聚焦从用户态到内核态的I2C设备通信实践。项目先使用WinRT API在用户模式下访问I2C设备进而开发KMDF内核驱动借助Simple Peripheral BusSPB与多个传感器通信读取温度并在LCD上显示同时配套用户模式程序通过符号链接和DeviceIoControl与驱动交互完整呈现了驱动框架、设备通信和上层调用链条。压缩包共38个文件大小仅1.83MB主要包括C头文件与实现h/cpp、Visual Studio工程文件sln/vcxproj、驱动跟踪消息头tmh、INX安装文件以及ACPI源语言ASL表等不同文件覆盖从驱动编译到设备表配置的各个阶段。目前已有51人浏览学习适合想快速理解KMDF与SPB驱动工作原理的开发者作为精简参照。1. 一条 I2C 总线上的事故现场0xFF 读数背后是驱动边界缺失第一次把 Windows 上位机直接挂到 I2C 总线上时我把希望全押在一根 USB-I2C 适配器上。结果一夜跑下来日志里堆满 0xFF换了三根线还是同一个毛病。最后换成 Sensy 这种基于 Windows 驱动框架WDF的 I2C 设备通信系统才意识到问题不在线材而在“应用层直接管总线”这个模型本身。Sensy 的思路一句话说清把 I2C 总线抽象成一个标准设备节点上位机只对着句柄读写时序、重试与错误恢复全部下沉到驱动程序。它适合产测软件、上位机监控和所有对时序一致性有要求的 Windows 场景——如果你也被 I2C 读回 0xFF 折磨过这个方向值得继续往下看。2. 先把架构想明白WDF 驱动框架怎么和 I2C 总线协议握手I2C 是两线制协议SDA 数据线加 SCL 时钟线总线事务的边界、ACK 位和 restart 条件都靠电平边沿来定义。Windows 内核并不原生“认识”I2C它提供的是 SPBSimple Peripheral Bus这套通用框架由 WDF 驱动通过 IOCTL 去控制总线传输。Sensy 这类系统本质上是在 WDF 里把 I2C 从机的寄存器访问包成一层内核设备再映射给应用层的 Win32 句柄。2.1 为什么是驱动框架而不是应用层直通如果只是临时读一个温度传感器用适配器厂商提供的 DLL 确实最快。但 Windows 上的应用层 DLL 有两个先天问题进程调度不可控总线事务没有原子性。I2C 总线上一个“写寄存器地址 读数据”的组合操作不允许中途被打断应用层线程一旦被调度出去SCL 上的时序就悬停从机很容易进入不可恢复的状态。Sensy 选择 KMDF 驱动模型让 IO 控制请求在内核态排队并由总线驱动完成事务“不允许被打断”这个约束才真正落到了实处。第二个理由是异常恢复能力。I2C 没有类似 CAN 的自动错误帧检测一个从机把 SCL 拉死整条总线上所有通信都会卡住。内核态驱动可以在总线层记录超时并在超时后主动翻转 9 个时钟周期来释放总线。这个动作在应用层 DLL 里很难做因为拿不到对应的内核资源。第三个点常常被忽略权限边界。应用层程序以普通用户身份运行也要能访问 I2C 设备。驱动设备节点通过 CreateFile 直接打开配合 Windows 的 ACL 可以精确到用户和组比给整个上位机进程提权到管理员要安全得多。用 Linux 那套词汇打比方Sensy 相当于在 Windows 上重建了一个字符设备驱动框架应用层看到的是一个可以 open/read/write 的设备节点而不是一个裸露的端口。2.2 数据链路拆解从 CreateFile 到从机寄存器的一个完整往返一条完整的读请求会经过这样一条链应用层 CreateFile 打开\\.\SensyDevice0拿到句柄后 DeviceIoControl 下发一个内嵌了从机地址、寄存器偏移和读长度的缓冲区I/O 管理器把它包成 IRPWDF 框架调度到 EvtIoDeviceControl 回调驱动解析参数后构造 I2C 传输描述符数组再通过 SPB 框架向底层控制器发起IOCTL_I2C_TRANSFER控制器产生 SCL/SDA 时序数据回到缓冲区驱动把内容复制回应用层。这条链路最容易翻车的地方在“组合事务”。很多新手把“写寄存器地址”和“读数据”拆成两次独立的 DeviceIoControl 调用这在总线上就是两段独立事务中间必然让出总线。如果总线上还有别的设备数据串位是大概率事件。驱动层要做的是把写和读放在同一个描述数组里由 SPB 框架处理成一次带 restart 条件的完整总线事务。提示判断驱动是否真的支持组合事务就看发送 IOCTL_I2C_TRANSFER 时传入的描述数组有几项。大于等于两项且在同一请求里下发的才是组合事务。2.3 参数落位地址、速度、超时和 ACK 处理驱动里最值得事先确定的参数就五类从机地址模式、总线时钟、组合事务结构、超时和重试次数。下面这张表是我在做这类驱动时常用的起点参数典型值说明从机地址7 位0x08~0x7710 位地址要单独设标志位总线时钟100 kHz / 400 kHz / 1 MHz以从机手册上限为准组合事务write readEEPROM 等从机必须超时10 ms ~ 100 ms时钟拉伸时按从机规格放大重试次数0 ~ 3 次对瞬时 NACK 有效对总线锁死无效地址换算是个经典细节。I2C 数据帧格式里7 位从机地址在总线上实际发送时要左移一位再补上读写位。7 位地址 0x50 写操作时对应 0xA0读操作对应 0xA1。这个换算散落在驱动各回调里很容易出错我在驱动里一般只留两个宏SENSY_ADDR_W(addr) ((addr) 1)和SENSY_ADDR_R(addr) (((addr) 1) | 1)所有派生处统一调用避免地址扫描和组合事务里用两套约定。ACK/NACK 处理也值得事前设计好。从机地址不对或寄存器索引非法从机会在 ACK 位回 NACKSPB 框架往往把这次传输标记为超时或设备未就绪。我的经验是把重试放在驱动层而不是应用层检测到 NACK 后重新发起一次 START最多 3 次仍失败再把错误原样返回同时把最后一次总线状态存进设备扩展方便排障时拉出来分析。3. 照着源码思路把驱动跑起来从 WDK 环境准备到第一次总线读写这一章按“拉一个最小可用驱动”的顺序走。你不需要一开始就照搬 Sensy 的全部设计只需要把设备对象、I2C 传输和应用层访问这条主链路跑通后面再逐步加功能。3.1 搭建 WDK 驱动编译环境与测试签名先装 Visual Studio然后在 VS 安装器里勾选 Windows 驱动程序工具集WDK组件。装完后要确认项目模板里能看到“Kernel Mode Driver (KMDF)”这一项。编译器位数要和目标系统一致现在绝大多数机器是 x64驱动工程也选 x64别默认编译成 x86。开发阶段建议直接开启测试签名模式省去每次改驱动都要签一遍证书的麻烦# 以管理员身份运行 PowerShell bcdedit /set testsigning on # 确认当前生效状态 bcdedit /enum {current}逻辑说明第一条命令修改引导配置允许加载未签名或测试签名的驱动第二条命令检查当前启动项的配置是否已启用测试签名。参数说明testsigning是开发调试常用的开关生产环境必须关闭改用正式代码签名证书。3.2 写最小驱动骨架DriverEntry 与设备初始化回调新建一个 KMDF 空工程把 DriverEntry 和 EvtDeviceAdd 这两个回调先搭起来。这段骨架是这类驱动的固定起点#include ntddk.h #include wdf.h DRIVER_INITIALIZE DriverEntry; typedef struct _DEVICE_CONTEXT { WDFIOTARGET I2CController; // 绑定的 I2C 控制器目标 ULONG BusSpeed; // 总线速率单位 kHz ULONG TimeoutMs; // 传输超时单位毫秒 UCHAR DefaultSlave; // 默认从机地址7 位 } DEVICE_CONTEXT, *PDEVICE_CONTEXT; WDF_DECLARE_CONTEXT_TYPE_WITH_NAME(DEVICE_CONTEXT, SensyGetCtx) NTSTATUS DriverEntry( _In_ PDRIVER_OBJECT DriverObject, _In_ PUNICODE_STRING RegistryPath ) { WDF_DRIVER_CONFIG config; NTSTATUS status; WDF_DRIVER_CONFIG_INIT(config, SensyEvtDeviceAdd); status WdfDriverCreate(DriverObject, RegistryPath, WDF_NO_OBJECT_ATTRIBUTES, config, WDF_NO_HANDLE); return status; }逻辑说明DriverEntry 是驱动唯一入口点WdfDriverCreate完成驱动对象注册并注册设备添加回调SensyEvtDeviceAdd。参数说明RegistryPath是驱动在注册表里的服务路径框架会自己管理这里不需要读写。设备上下文用WDF_DECLARE_CONTEXT_TYPE_WITH_NAME声明方便在后续回调里安全取用。3.3 实现 I2C 组合读写EvtIoDeviceControl 与描述符数组驱动对应用层暴露功能最朴素的通道就是 DeviceIoControl。先把 IOCTL 分派回调写好再把核心的组合读实现补上#define IOCTL_SENSY_I2C_COMBINED_READ \ CTL_CODE(FILE_DEVICE_UNKNOWN, 0x801, METHOD_BUFFERED, FILE_ANY_ACCESS) #define IOCTL_SENSY_I2C_WRITE \ CTL_CODE(FILE_DEVICE_UNKNOWN, 0x802, METHOD_BUFFERED, FILE_ANY_ACCESS) VOID SensyEvtIoDeviceControl( _In_ WDFQUEUE Queue, _In_ WDFREQUEST Request, _In_ size_t OutputBufferLength, _In_ size_t InputBufferLength, _In_ ULONG IoControlCode ) { NTSTATUS status STATUS_SUCCESS; PDEVICE_CONTEXT ctx SensyGetCtx(WdfIoQueueGetDevice(Queue)); switch (IoControlCode) { case IOCTL_SENSY_I2C_COMBINED_READ: status SensyCombinedRead(ctx, Request); break; case IOCTL_SENSY_I2C_WRITE: status SensyBusWrite(ctx, Request); break; default: status STATUS_INVALID_DEVICE_REQUEST; break; } WdfRequestComplete(Request, status); }逻辑说明WdfIoQueueGetDevice从队列拿到设备对象再取到设备上下文。串行队列模式下同一时间只放行一个 I2C 请求这是保证总线原子性的关键。CTL_CODE里的METHOD_BUFFERED表示输入输出共用同一个系统缓冲区驱动侧用WdfRequestRetrieveInputBuffer和WdfRequestRetrieveOutputBuffer访问。组合读内部的核心是构造传输描述符数组NTSTATUS SensyCombinedRead( _In_ PDEVICE_CONTEXT Ctx, _In_ WDFREQUEST Request ) { PSENSY_READ_REQ inBuf; // 应用层输入地址、寄存器、长度 PUCHAR outBuf; // 输出缓冲区读回的数据 I2C_TRANSFER_DESCRIPTOR desc[2]; NTSTATUS status; // 从请求里取出应用层传入的参数 status WdfRequestRetrieveInputBuffer(Request, sizeof(*inBuf), (PVOID*)inBuf, NULL); if (!NT_SUCCESS(status)) { return status; } status WdfRequestRetrieveOutputBuffer(Request, inBuf-ReadLen, (PVOID*)outBuf, NULL); if (!NT_SUCCESS(status)) { return status; } // 段 1写寄存器地址方向为写 desc[0].Length inBuf-RegLen; desc[0].Flags I2C_AP_TRANSFER_WRITE; desc[0].Buffer inBuf-RegAddr; // 段 2读数据方向为读SPB 会在两段间插入 restart desc[1].Length inBuf-ReadLen; desc[1].Flags I2C_AP_TRANSFER_READ; desc[1].Buffer outBuf; // 把两个描述符一次性下发给 SPB 控制器 status SensySubmitTransfer(Ctx, inBuf-SlaveAddr, desc, 2); return status; }逻辑说明段 1 是写操作把寄存器地址送上总线段 2 是读操作数据直接落到outBuf。两个描述符在同一个请求里提交SPB 框架会保证中间不释放总线。参数说明I2C_AP_TRANSFER_READ和I2C_AP_TRANSFER_WRITE的具体名称以你所用 WDK 版本头文件为准有的版本还要求显式加I2C_AP_TRANSFER_STOP标志习惯上是最后一段加 STOP。3.4 应用层用 CreateFile 打开设备并完成第一次读驱动装好之后应用层就能用标准 Win32 API 访问。注意设备路径要和驱动在代码里设置的设备接口 GUID 一致这里假设安装后设备符号链接为\\.\SensyDevice0HANDLE hDev CreateFileW(L\\\\.\\SensyDevice0, GENERIC_READ | GENERIC_WRITE, 0, NULL, OPEN_EXISTING, 0, NULL); if (hDev INVALID_HANDLE_VALUE) { // 检查 GetLastError()常见 2 或 3设备路径没配对 } SENSY_READ_REQ req { 0 }; BYTE buf[8] { 0 }; DWORD retLen 0; req.SlaveAddr 0x50; // EEPROM 的 7 位地址 req.RegAddr 0x00; // 从 0x0000 寄存器开始 req.RegLen 1; // 地址占 1 字节 req.ReadLen 8; // 连续读 8 个字节 BOOL ok DeviceIoControl(hDev, IOCTL_SENSY_I2C_COMBINED_READ, req, sizeof(req), buf, sizeof(buf), retLen, NULL); if (ok) { // 此时 buf[0..7] 就是 EEPROM 前 8 字节 } CloseHandle(hDev);逻辑说明SENSY_READ_REQ是应用层和驱动约定的输入结构包含从机地址、寄存器地址和长度。DeviceIoControl的输入缓冲区传请求结构输出缓冲区收读回的数据。参数说明GENERIC_READ | GENERIC_WRITE是访问权限OPEN_EXISTING要求设备节点已存在如果驱动没加载或路径写错CreateFile会失败先看事件查看器里的驱动加载日志。3.5 编译、签名、加载与快速验证全部代码就绪后编译和安装这一步要按顺序来# 编译 64 位 Debug 驱动 msbuild Sensy.sln /p:ConfigurationDebug /p:Platformx64 /m # 开启测试签名后重启再安装驱动 pnputil /add-driver Sensy.inf /install逻辑说明msbuild直接编译解决方案Debug 配置下生成的驱动可以配合 WinDbg 调试。pnputil是 Windows 自带的驱动安装工具/add-driver添加驱动包/install立即对匹配的设备执行安装。参数说明如果设备是 ACPI 枚举的 I2C 从机inf里要写对硬件 ID如果是动态创建的软件设备则要考虑用设备接口 GUID 让应用层能找到节点。4. 驱动跑起来之后的避坑清单签名、代码 10 与总线锁死这一章列出我在这个方向上踩过且值得记录的五个坑。每一条不保证所有环境都复现但现象、原因和解决思路是通用的。4.1 安装阶段的坑驱动签名和代码 10坑一Windows 提示“无法验证此设备驱动程序的数字签名”。现象是安装驱动时系统直接拒绝设备管理器里出现黄色感叹号。原因是开发阶段没签名或只签了测试证书。解决方法是先执行bcdedit /set testsigning on并重启再用signtool sign给.sys文件签名最后用inf2cat /driver:... /os:10_X64生成目录文件把签名附到目录文件上。生产环境要换正式代码签名证书测试签名不能带到现场。坑二设备管理器报“Windows 无法启动这个硬件设备代码 10”。现象是驱动安装成功但设备起不来。原因比较多最常见是EvtDeviceAdd里某个初始化失败直接返回了错误或者驱动绑定的 I2C 控制器路径不匹配。解决方法是先用 WinDbg 挂内核调试断点在DriverEntry和设备回调入口看返回的 NTSTATUS再确认 ACPI 表里声明的 I2C 控制器资源与 WDF 打开的目标路径一致。务实一点的做法是先把所有初始化步骤拆开逐步回归定位到具体哪一个 API 失败。4.2 通信阶段的坑超时、0xFF 和 ERROR_INVALID_PARAMETER坑三DeviceIoControl 返回 121STATUS_TIMEOUT。现象是读操作偶尔超时重试几次又能成功。原因是总线速率设太高从机跟不上或者总线上存在地址冲突从机在争抢 ACK 位。解决方法是先把驱动里的BusSpeed降到 100 kHz用示波器抓 SCL 和 SDA确认每个字节的 ACK 位是否正常再逐一遍历从机地址确认没有两个设备用了同一地址。时钟拉伸也是超时的高发原因从机把 SCL 拉低后要检查它的拉伸时间是否超过驱动的超时上限。坑四读回来的数据全是 0xFF或者位置错乱。现象是数据能读回但内容不对。原因最常见是两个地址换算出错7 位地址当 8 位用导致总线上的设备不对另一个是组合事务被拆成了两次独立请求中间插入别的总线访问。解决方法是统一用SENSY_ADDR_W/R宏做换算别在多个回调里各写一套再把组合读的验证写成驱动内的单元测试固定读一个已知寄存器读 100 次对比内容。提示7 位地址 0x50 在总线上实际发送的字节是 0xA0 / 0xA1。驱动层如果按“device address R/W bit”拼装就别再手动左移这个坑几乎每个新项目都会踩一次。坑五DeviceIoControl 直接返回 87ERROR_INVALID_PARAMETER。现象是应用层一调用就失败驱动回调甚至没进。原因是 IOCTL 的缓冲区访问方式和实际传入长度不匹配。METHOD_BUFFERED模式下驱动侧用WdfRequestRetrieveInputBuffer要求最小长度应用层传的结构体太小就会失败。解决方法是确认SENSY_READ_REQ结构体在应用层和驱动侧定义一致特别是结构体对齐方式32 位和 64 位程序混用时尤其容易踩。5. 把 Sensy 做成产线能用的状态机自检指令、失败重试和恢复线索5.1 给驱动加一个总线自检 IOCTL我经手这类系统的做法是在驱动里预留一个IOCTL_SENSY_SELF_TEST。它的逻辑不复杂挑一个固定寄存器地址做组合读写连续执行 10 次全部通过才返回成功任何一次失败就返回错误码并把失败时的寄存器地址、从机地址和总线状态一并放到输出缓冲区。这个自检指令在生产环境里价值很大产线上位机每次启动前都先跑一遍跑不通就不往下推进。5.2 把失败重试和状态码留到驱动层产线场景里上位机换班、断电重启、夹具松动都会让 I2C 通信出问题。如果重试逻辑放在应用层每个上位机开发者的重试策略都不一样出了问题很难统一排查。我一般把重试下沉到驱动层NACK 重发、总线释放、再次发起 START这些动作对应用层透明。应用层只收到最终结果同时驱动把最近一次失败的详细状态留在设备扩展里用另一个 IOCTL 读取相当于给驱动留了一扇能看到内部状态的窗口。早期翻过车适配器刚插上时能通灌了半小时数据就死排查时总线状态完全看不进去整个就是黑匣子。后来我坚持在驱动里做总线自检和失败留痕产线再出问题几分钟就能定位是夹具接触不良还是从机寄存器越界。如果你也要做 Windows 下的 I2C 设备通信建议先按第 3 章把最小驱动跑通再把自检和重试补上这两步能帮你省掉大半现场调试时间。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/8 6:00:42 · 阅读 1.2k Windows下I2C设备驱动实战：基于WDF框架解决总线通信与0xFF问题
简介Sensy是一份面向嵌入式与Windows驱动开发学习者的教育型项目源码包聚焦从用户态到内核态的I2C设备通信实践。项目先使用WinRT API在用户模式下访问I2C设备进而开发KMDF内核驱动借助Simple Peripheral BusSPB与多个传感器通信读取温度并在LCD上显示同时配套用户模式程序通过符号链接和DeviceIoControl与驱动交互完整呈现了驱动框架、设备通信和上层调用链条。压缩包共38个文件大小仅1.83MB主要包括C头文件与实现h/cpp、Visual Studio工程文件sln/vcxproj、驱动跟踪消息头tmh、INX安装文件以及ACPI源语言ASL表等不同文件覆盖从驱动编译到设备表配置的各个阶段。目前已有51人浏览学习适合想快速理解KMDF与SPB驱动工作原理的开发者作为精简参照。1. 一条 I2C 总线上的事故现场0xFF 读数背后是驱动边界缺失第一次把 Windows 上位机直接挂到 I2C 总线上时我把希望全押在一根 USB-I2C 适配器上。结果一夜跑下来日志里堆满 0xFF换了三根线还是同一个毛病。最后换成 Sensy 这种基于 Windows 驱动框架WDF的 I2C 设备通信系统才意识到问题不在线材而在“应用层直接管总线”这个模型本身。Sensy 的思路一句话说清把 I2C 总线抽象成一个标准设备节点上位机只对着句柄读写时序、重试与错误恢复全部下沉到驱动程序。它适合产测软件、上位机监控和所有对时序一致性有要求的 Windows 场景——如果你也被 I2C 读回 0xFF 折磨过这个方向值得继续往下看。2. 先把架构想明白WDF 驱动框架怎么和 I2C 总线协议握手I2C 是两线制协议SDA 数据线加 SCL 时钟线总线事务的边界、ACK 位和 restart 条件都靠电平边沿来定义。Windows 内核并不原生“认识”I2C它提供的是 SPBSimple Peripheral Bus这套通用框架由 WDF 驱动通过 IOCTL 去控制总线传输。Sensy 这类系统本质上是在 WDF 里把 I2C 从机的寄存器访问包成一层内核设备再映射给应用层的 Win32 句柄。2.1 为什么是驱动框架而不是应用层直通如果只是临时读一个温度传感器用适配器厂商提供的 DLL 确实最快。但 Windows 上的应用层 DLL 有两个先天问题进程调度不可控总线事务没有原子性。I2C 总线上一个“写寄存器地址 读数据”的组合操作不允许中途被打断应用层线程一旦被调度出去SCL 上的时序就悬停从机很容易进入不可恢复的状态。Sensy 选择 KMDF 驱动模型让 IO 控制请求在内核态排队并由总线驱动完成事务“不允许被打断”这个约束才真正落到了实处。第二个理由是异常恢复能力。I2C 没有类似 CAN 的自动错误帧检测一个从机把 SCL 拉死整条总线上所有通信都会卡住。内核态驱动可以在总线层记录超时并在超时后主动翻转 9 个时钟周期来释放总线。这个动作在应用层 DLL 里很难做因为拿不到对应的内核资源。第三个点常常被忽略权限边界。应用层程序以普通用户身份运行也要能访问 I2C 设备。驱动设备节点通过 CreateFile 直接打开配合 Windows 的 ACL 可以精确到用户和组比给整个上位机进程提权到管理员要安全得多。用 Linux 那套词汇打比方Sensy 相当于在 Windows 上重建了一个字符设备驱动框架应用层看到的是一个可以 open/read/write 的设备节点而不是一个裸露的端口。2.2 数据链路拆解从 CreateFile 到从机寄存器的一个完整往返一条完整的读请求会经过这样一条链应用层 CreateFile 打开\\.\SensyDevice0拿到句柄后 DeviceIoControl 下发一个内嵌了从机地址、寄存器偏移和读长度的缓冲区I/O 管理器把它包成 IRPWDF 框架调度到 EvtIoDeviceControl 回调驱动解析参数后构造 I2C 传输描述符数组再通过 SPB 框架向底层控制器发起IOCTL_I2C_TRANSFER控制器产生 SCL/SDA 时序数据回到缓冲区驱动把内容复制回应用层。这条链路最容易翻车的地方在“组合事务”。很多新手把“写寄存器地址”和“读数据”拆成两次独立的 DeviceIoControl 调用这在总线上就是两段独立事务中间必然让出总线。如果总线上还有别的设备数据串位是大概率事件。驱动层要做的是把写和读放在同一个描述数组里由 SPB 框架处理成一次带 restart 条件的完整总线事务。提示判断驱动是否真的支持组合事务就看发送 IOCTL_I2C_TRANSFER 时传入的描述数组有几项。大于等于两项且在同一请求里下发的才是组合事务。2.3 参数落位地址、速度、超时和 ACK 处理驱动里最值得事先确定的参数就五类从机地址模式、总线时钟、组合事务结构、超时和重试次数。下面这张表是我在做这类驱动时常用的起点参数典型值说明从机地址7 位0x08~0x7710 位地址要单独设标志位总线时钟100 kHz / 400 kHz / 1 MHz以从机手册上限为准组合事务write readEEPROM 等从机必须超时10 ms ~ 100 ms时钟拉伸时按从机规格放大重试次数0 ~ 3 次对瞬时 NACK 有效对总线锁死无效地址换算是个经典细节。I2C 数据帧格式里7 位从机地址在总线上实际发送时要左移一位再补上读写位。7 位地址 0x50 写操作时对应 0xA0读操作对应 0xA1。这个换算散落在驱动各回调里很容易出错我在驱动里一般只留两个宏SENSY_ADDR_W(addr) ((addr) 1)和SENSY_ADDR_R(addr) (((addr) 1) | 1)所有派生处统一调用避免地址扫描和组合事务里用两套约定。ACK/NACK 处理也值得事前设计好。从机地址不对或寄存器索引非法从机会在 ACK 位回 NACKSPB 框架往往把这次传输标记为超时或设备未就绪。我的经验是把重试放在驱动层而不是应用层检测到 NACK 后重新发起一次 START最多 3 次仍失败再把错误原样返回同时把最后一次总线状态存进设备扩展方便排障时拉出来分析。3. 照着源码思路把驱动跑起来从 WDK 环境准备到第一次总线读写这一章按“拉一个最小可用驱动”的顺序走。你不需要一开始就照搬 Sensy 的全部设计只需要把设备对象、I2C 传输和应用层访问这条主链路跑通后面再逐步加功能。3.1 搭建 WDK 驱动编译环境与测试签名先装 Visual Studio然后在 VS 安装器里勾选 Windows 驱动程序工具集WDK组件。装完后要确认项目模板里能看到“Kernel Mode Driver (KMDF)”这一项。编译器位数要和目标系统一致现在绝大多数机器是 x64驱动工程也选 x64别默认编译成 x86。开发阶段建议直接开启测试签名模式省去每次改驱动都要签一遍证书的麻烦# 以管理员身份运行 PowerShell bcdedit /set testsigning on # 确认当前生效状态 bcdedit /enum {current}逻辑说明第一条命令修改引导配置允许加载未签名或测试签名的驱动第二条命令检查当前启动项的配置是否已启用测试签名。参数说明testsigning是开发调试常用的开关生产环境必须关闭改用正式代码签名证书。3.2 写最小驱动骨架DriverEntry 与设备初始化回调新建一个 KMDF 空工程把 DriverEntry 和 EvtDeviceAdd 这两个回调先搭起来。这段骨架是这类驱动的固定起点#include ntddk.h #include wdf.h DRIVER_INITIALIZE DriverEntry; typedef struct _DEVICE_CONTEXT { WDFIOTARGET I2CController; // 绑定的 I2C 控制器目标 ULONG BusSpeed; // 总线速率单位 kHz ULONG TimeoutMs; // 传输超时单位毫秒 UCHAR DefaultSlave; // 默认从机地址7 位 } DEVICE_CONTEXT, *PDEVICE_CONTEXT; WDF_DECLARE_CONTEXT_TYPE_WITH_NAME(DEVICE_CONTEXT, SensyGetCtx) NTSTATUS DriverEntry( _In_ PDRIVER_OBJECT DriverObject, _In_ PUNICODE_STRING RegistryPath ) { WDF_DRIVER_CONFIG config; NTSTATUS status; WDF_DRIVER_CONFIG_INIT(config, SensyEvtDeviceAdd); status WdfDriverCreate(DriverObject, RegistryPath, WDF_NO_OBJECT_ATTRIBUTES, config, WDF_NO_HANDLE); return status; }逻辑说明DriverEntry 是驱动唯一入口点WdfDriverCreate完成驱动对象注册并注册设备添加回调SensyEvtDeviceAdd。参数说明RegistryPath是驱动在注册表里的服务路径框架会自己管理这里不需要读写。设备上下文用WDF_DECLARE_CONTEXT_TYPE_WITH_NAME声明方便在后续回调里安全取用。3.3 实现 I2C 组合读写EvtIoDeviceControl 与描述符数组驱动对应用层暴露功能最朴素的通道就是 DeviceIoControl。先把 IOCTL 分派回调写好再把核心的组合读实现补上#define IOCTL_SENSY_I2C_COMBINED_READ \ CTL_CODE(FILE_DEVICE_UNKNOWN, 0x801, METHOD_BUFFERED, FILE_ANY_ACCESS) #define IOCTL_SENSY_I2C_WRITE \ CTL_CODE(FILE_DEVICE_UNKNOWN, 0x802, METHOD_BUFFERED, FILE_ANY_ACCESS) VOID SensyEvtIoDeviceControl( _In_ WDFQUEUE Queue, _In_ WDFREQUEST Request, _In_ size_t OutputBufferLength, _In_ size_t InputBufferLength, _In_ ULONG IoControlCode ) { NTSTATUS status STATUS_SUCCESS; PDEVICE_CONTEXT ctx SensyGetCtx(WdfIoQueueGetDevice(Queue)); switch (IoControlCode) { case IOCTL_SENSY_I2C_COMBINED_READ: status SensyCombinedRead(ctx, Request); break; case IOCTL_SENSY_I2C_WRITE: status SensyBusWrite(ctx, Request); break; default: status STATUS_INVALID_DEVICE_REQUEST; break; } WdfRequestComplete(Request, status); }逻辑说明WdfIoQueueGetDevice从队列拿到设备对象再取到设备上下文。串行队列模式下同一时间只放行一个 I2C 请求这是保证总线原子性的关键。CTL_CODE里的METHOD_BUFFERED表示输入输出共用同一个系统缓冲区驱动侧用WdfRequestRetrieveInputBuffer和WdfRequestRetrieveOutputBuffer访问。组合读内部的核心是构造传输描述符数组NTSTATUS SensyCombinedRead( _In_ PDEVICE_CONTEXT Ctx, _In_ WDFREQUEST Request ) { PSENSY_READ_REQ inBuf; // 应用层输入地址、寄存器、长度 PUCHAR outBuf; // 输出缓冲区读回的数据 I2C_TRANSFER_DESCRIPTOR desc[2]; NTSTATUS status; // 从请求里取出应用层传入的参数 status WdfRequestRetrieveInputBuffer(Request, sizeof(*inBuf), (PVOID*)inBuf, NULL); if (!NT_SUCCESS(status)) { return status; } status WdfRequestRetrieveOutputBuffer(Request, inBuf-ReadLen, (PVOID*)outBuf, NULL); if (!NT_SUCCESS(status)) { return status; } // 段 1写寄存器地址方向为写 desc[0].Length inBuf-RegLen; desc[0].Flags I2C_AP_TRANSFER_WRITE; desc[0].Buffer inBuf-RegAddr; // 段 2读数据方向为读SPB 会在两段间插入 restart desc[1].Length inBuf-ReadLen; desc[1].Flags I2C_AP_TRANSFER_READ; desc[1].Buffer outBuf; // 把两个描述符一次性下发给 SPB 控制器 status SensySubmitTransfer(Ctx, inBuf-SlaveAddr, desc, 2); return status; }逻辑说明段 1 是写操作把寄存器地址送上总线段 2 是读操作数据直接落到outBuf。两个描述符在同一个请求里提交SPB 框架会保证中间不释放总线。参数说明I2C_AP_TRANSFER_READ和I2C_AP_TRANSFER_WRITE的具体名称以你所用 WDK 版本头文件为准有的版本还要求显式加I2C_AP_TRANSFER_STOP标志习惯上是最后一段加 STOP。3.4 应用层用 CreateFile 打开设备并完成第一次读驱动装好之后应用层就能用标准 Win32 API 访问。注意设备路径要和驱动在代码里设置的设备接口 GUID 一致这里假设安装后设备符号链接为\\.\SensyDevice0HANDLE hDev CreateFileW(L\\\\.\\SensyDevice0, GENERIC_READ | GENERIC_WRITE, 0, NULL, OPEN_EXISTING, 0, NULL); if (hDev INVALID_HANDLE_VALUE) { // 检查 GetLastError()常见 2 或 3设备路径没配对 } SENSY_READ_REQ req { 0 }; BYTE buf[8] { 0 }; DWORD retLen 0; req.SlaveAddr 0x50; // EEPROM 的 7 位地址 req.RegAddr 0x00; // 从 0x0000 寄存器开始 req.RegLen 1; // 地址占 1 字节 req.ReadLen 8; // 连续读 8 个字节 BOOL ok DeviceIoControl(hDev, IOCTL_SENSY_I2C_COMBINED_READ, req, sizeof(req), buf, sizeof(buf), retLen, NULL); if (ok) { // 此时 buf[0..7] 就是 EEPROM 前 8 字节 } CloseHandle(hDev);逻辑说明SENSY_READ_REQ是应用层和驱动约定的输入结构包含从机地址、寄存器地址和长度。DeviceIoControl的输入缓冲区传请求结构输出缓冲区收读回的数据。参数说明GENERIC_READ | GENERIC_WRITE是访问权限OPEN_EXISTING要求设备节点已存在如果驱动没加载或路径写错CreateFile会失败先看事件查看器里的驱动加载日志。3.5 编译、签名、加载与快速验证全部代码就绪后编译和安装这一步要按顺序来# 编译 64 位 Debug 驱动 msbuild Sensy.sln /p:ConfigurationDebug /p:Platformx64 /m # 开启测试签名后重启再安装驱动 pnputil /add-driver Sensy.inf /install逻辑说明msbuild直接编译解决方案Debug 配置下生成的驱动可以配合 WinDbg 调试。pnputil是 Windows 自带的驱动安装工具/add-driver添加驱动包/install立即对匹配的设备执行安装。参数说明如果设备是 ACPI 枚举的 I2C 从机inf里要写对硬件 ID如果是动态创建的软件设备则要考虑用设备接口 GUID 让应用层能找到节点。4. 驱动跑起来之后的避坑清单签名、代码 10 与总线锁死这一章列出我在这个方向上踩过且值得记录的五个坑。每一条不保证所有环境都复现但现象、原因和解决思路是通用的。4.1 安装阶段的坑驱动签名和代码 10坑一Windows 提示“无法验证此设备驱动程序的数字签名”。现象是安装驱动时系统直接拒绝设备管理器里出现黄色感叹号。原因是开发阶段没签名或只签了测试证书。解决方法是先执行bcdedit /set testsigning on并重启再用signtool sign给.sys文件签名最后用inf2cat /driver:... /os:10_X64生成目录文件把签名附到目录文件上。生产环境要换正式代码签名证书测试签名不能带到现场。坑二设备管理器报“Windows 无法启动这个硬件设备代码 10”。现象是驱动安装成功但设备起不来。原因比较多最常见是EvtDeviceAdd里某个初始化失败直接返回了错误或者驱动绑定的 I2C 控制器路径不匹配。解决方法是先用 WinDbg 挂内核调试断点在DriverEntry和设备回调入口看返回的 NTSTATUS再确认 ACPI 表里声明的 I2C 控制器资源与 WDF 打开的目标路径一致。务实一点的做法是先把所有初始化步骤拆开逐步回归定位到具体哪一个 API 失败。4.2 通信阶段的坑超时、0xFF 和 ERROR_INVALID_PARAMETER坑三DeviceIoControl 返回 121STATUS_TIMEOUT。现象是读操作偶尔超时重试几次又能成功。原因是总线速率设太高从机跟不上或者总线上存在地址冲突从机在争抢 ACK 位。解决方法是先把驱动里的BusSpeed降到 100 kHz用示波器抓 SCL 和 SDA确认每个字节的 ACK 位是否正常再逐一遍历从机地址确认没有两个设备用了同一地址。时钟拉伸也是超时的高发原因从机把 SCL 拉低后要检查它的拉伸时间是否超过驱动的超时上限。坑四读回来的数据全是 0xFF或者位置错乱。现象是数据能读回但内容不对。原因最常见是两个地址换算出错7 位地址当 8 位用导致总线上的设备不对另一个是组合事务被拆成了两次独立请求中间插入别的总线访问。解决方法是统一用SENSY_ADDR_W/R宏做换算别在多个回调里各写一套再把组合读的验证写成驱动内的单元测试固定读一个已知寄存器读 100 次对比内容。提示7 位地址 0x50 在总线上实际发送的字节是 0xA0 / 0xA1。驱动层如果按“device address R/W bit”拼装就别再手动左移这个坑几乎每个新项目都会踩一次。坑五DeviceIoControl 直接返回 87ERROR_INVALID_PARAMETER。现象是应用层一调用就失败驱动回调甚至没进。原因是 IOCTL 的缓冲区访问方式和实际传入长度不匹配。METHOD_BUFFERED模式下驱动侧用WdfRequestRetrieveInputBuffer要求最小长度应用层传的结构体太小就会失败。解决方法是确认SENSY_READ_REQ结构体在应用层和驱动侧定义一致特别是结构体对齐方式32 位和 64 位程序混用时尤其容易踩。5. 把 Sensy 做成产线能用的状态机自检指令、失败重试和恢复线索5.1 给驱动加一个总线自检 IOCTL我经手这类系统的做法是在驱动里预留一个IOCTL_SENSY_SELF_TEST。它的逻辑不复杂挑一个固定寄存器地址做组合读写连续执行 10 次全部通过才返回成功任何一次失败就返回错误码并把失败时的寄存器地址、从机地址和总线状态一并放到输出缓冲区。这个自检指令在生产环境里价值很大产线上位机每次启动前都先跑一遍跑不通就不往下推进。5.2 把失败重试和状态码留到驱动层产线场景里上位机换班、断电重启、夹具松动都会让 I2C 通信出问题。如果重试逻辑放在应用层每个上位机开发者的重试策略都不一样出了问题很难统一排查。我一般把重试下沉到驱动层NACK 重发、总线释放、再次发起 START这些动作对应用层透明。应用层只收到最终结果同时驱动把最近一次失败的详细状态留在设备扩展里用另一个 IOCTL 读取相当于给驱动留了一扇能看到内部状态的窗口。早期翻过车适配器刚插上时能通灌了半小时数据就死排查时总线状态完全看不进去整个就是黑匣子。后来我坚持在驱动里做总线自检和失败留痕产线再出问题几分钟就能定位是夹具接触不良还是从机寄存器越界。如果你也要做 Windows 下的 I2C 设备通信建议先按第 3 章把最小驱动跑通再把自检和重试补上这两步能帮你省掉大半现场调试时间。希望帮到你。本文还有配套的精品资源点击获取