Windows 驱动实例分析系列：libwdi 驱动分析 - libwdi 篇(一)

子文档一：libwdi 核心库概述与整体架构

libwdi 的核心库代码位于 libwdi/ 目录下，这是整个项目的功能主体 。该目录包含约 20 个 C 源文件和头文件，共同构成了一个自包含的 Windows USB 驱动安装库。与 examples/ 目录中的示例程序不同，核心库不依赖任何外部资源，所有必需的驱动二进制、模板文件、安装器可执行文件均以二进制数组的形式嵌入到库中。

目录结构解析

libwdi/
├── libwdi.h              # 对外 API 声明（公共接口）
├── libwdi.c              # 主要 API 实现（设备枚举、驱动准备、安装调度）
├── libwdi_i.h            # 内部头文件（私有数据结构、函数声明）
├── libwdi_dlg.c          # 进度条对话框实现（GUI 模式安装）
├── embedder.c            # 资源嵌入工具（构建时生成 embedded.h）
├── embedder.h            # 嵌入工具配置宏
├── embedder_files.h      # 需要嵌入的文件清单
├── installer.c           # 提权安装器主程序（独立进程）
├── installer.h           # 安装器内部头文件（管道协议、辅助宏）
├── tokenizer.c           # 令牌替换引擎（用于 INF/CAT 模板）
├── tokenizer.h           # 令牌引擎接口
├── pki.c                 # PKI 模块（证书创建、CAT 签名、自签名）
├── mssign32.h            # MSSign32 API 声明（代码签名）
├── logging.c             # 日志系统（管道 + 窗口消息）
├── logging.h             # 日志接口宏
├── vid_data.c            # USB VID 厂商名称数据库（自动生成）
├── msapi_utf8.h          # UTF-8 版本 Windows API 封装
├── stdfn.h               # 通用辅助宏与函数
├── resource.h            # 资源 ID（用于进度条对话框）
├── config.h              # 编译配置（由 msvc/config.h 或 configure 生成）
└── embedded.h            # 由 embedder 生成，包含所有嵌入资源数据

设计分层

核心库采用三层架构：

1. 资源层 ：embedder 在构建时将各类文件（驱动 .sys/.dll、INF 模板、CAT 模板、安装器 .exe）转换为 C 数组，生成 embedded.h。vid_data.c 提供了 VID 到厂商名称的静态映射表。

2. 逻辑层：

   • libwdi.c：实现对外 API，协调各子模块完成设备枚举、驱动准备和安装。
   • tokenizer.c：提供模板替换能力，用于动态生成 INF 和 CAT 文件内容。
   • pki.c：实现自签名证书的创建、安装、CAT 文件生成和签名。
   • installer.c：作为独立进程处理实际的驱动安装操作（需管理员权限）。
   • libwdi_dlg.c：提供带进度条的模态对话框，用于在 GUI 应用中显示安装进度。

3. 适配层：

   • msapi_utf8.h：将所有 Windows API 封装为 UTF-8 版本，使核心代码统一使用 UTF-8 编码。
   • logging.c：提供跨进程日志收集和分发机制。
   • stdfn.h：提供安全字符串操作、注册表读写等通用功能。

模块间协作关系

• libwdi.c 是总控制器，它调用 tokenizer 生成 INF，调用 pki 生成 CAT，然后通过 installer 执行实际安装。
• installer.c 是一个独立的可执行文件，通过命名管道与 libwdi.c 通信，获取设备信息并回传日志和状态。
• logging.c 提供独立的日志管道，用于将内部日志实时传递给注册的窗口（如 Zadig 的日志窗口）。
• libwdi_dlg.c 仅在 wdi_install_driver 被调用且传入了 hWnd 时激活，它会创建一个进度对话框并在后台线程中执行安装逻辑。

这种设计使得 libwdi 既可以用于控制台应用（无 UI），也可以无缝集成到图形界面中，同时保证了权限隔离（普通用户权限与管理员权限分离）和资源自包含。

---