windows-drivers-rs

这个仓库是一系列Rust crate的集合，使开发人员能够用Rust开发Windows驱动程序。我们的目标是同时支持WDM和WDF驱动程序开发模型。该仓库包含以下crate：

• wdk-build：一个库，用于配置Cargo构建脚本，以生成绑定并链接WDK（Windows驱动程序工具包）。虽然这个crate设计得可以灵活适应不同的WDK发布版本和不同的WDF版本，但目前仅针对NI eWDK、KMDF 1.33、UMDF 2.33和WDM驱动程序进行了测试。对于较旧的DDK可能缺少一些链接器选项。
• wdk-sys：Windows开发工具包（WDK）中可用API的直接FFI绑定。这包括由bindgen自动生成的FFI绑定，以及bindgen无法生成的宏的手动重新实现。
• wdk：Windows开发工具包（WDK）中可用API的安全惯用绑定。
• wdk-panic：使用WDK构建的程序的默认panic处理程序实现。
• wdk-alloc：为使用Windows开发工具包（WDK）编译的二进制文件提供alloc支持。
• wdk-macros：一系列宏，帮助更容易地与wdk-sys的直接绑定进行交互。这个crate通过wdk-sys重新导出，通常crate不需要直接依赖wdk-macros。

要查看使用此仓库创建驱动程序的示例，请参阅Windows-rust-driver-samples。

注意：该项目仍处于早期开发阶段，暂不建议用于生产环境。我们鼓励社区进行实验、提出建议和讨论！我们将使用GitHub讨论论坛作为与社区互动的主要形式！

<a name="supported-configs">支持的配置

本项目的构建考虑了对WDM、KMDF和UMDF驱动程序以及Win32服务的支持。这包括支持WDK 22H2及更新版本中包含的所有WDF版本。目前，在crates.io上可用的crate仅支持KMDF v1.33，但可以通过克隆windows-drivers-rs并修改wdk-sys的build.rs中指定的配置来为其他版本生成绑定。计划在不久的将来为其他WDK配置提供crates.io支持。

入门指南

构建要求

• 通过bindgen生成绑定需要libclang。获取它的最简单方法是通过winget

  • winget install -i LLVM.LLVM --version 17.0.6 --force
    • 确保选择GUI选项将LLVM添加到PATH中
    • LLVM 18存在一个bug，导致ARM64的绑定生成失败。继续使用LLVM 17，直到LLVM 19发布修复。有关更多详细信息，请参阅此处。

• 要执行构建后任务（如inf2cat、infverif等），使用cargo make

  • cargo install --locked cargo-make --no-default-features --features tls-native

• 使用WDK构建程序还需要在有效的WDK环境中进行。推荐的方法是进入eWDK开发人员提示符

将windows-drivers-rs添加到您的驱动程序包中

本仓库中的crate可从crates.io获得，但请注意支持的配置中概述的当前限制。如果您需要支持不同的配置，请尝试克隆此仓库并使用路径依赖

1. 创建一个新的Cargo包，包含一个lib crate：

   cargo new <driver_name> --lib

2. 添加对windows-drivers-rs crate的依赖：

   cd <driver_name>
   cargo add --build wdk-build
   cargo add wdk wdk-sys wdk-alloc wdk-panic

3. 通过在Cargo.toml中添加以下片段，将crate类型设置为cdylib：

   [lib]
   crate-type = ["cdylib"]

4. 使用wdk元数据部分将crate标记为驱动程序。这让cargo-make任务知道该包是一个驱动程序，需要运行驱动程序打包步骤。

   [package.metadata.wdk]

5. 在Cargo.toml中设置crate的panic策略为abort：

   [profile.dev]
   panic = "abort"
   lto = true # 可选设置，启用链接时优化
   
   [profile.release]
   panic = "abort"
   lto = true # 可选设置，启用链接时优化

6. 创建一个build.rs并添加以下片段：

   fn main() -> Result<(), wdk_build::ConfigError> {
      wdk_build::Config::from_env_auto()?.configure_binary_build()?;
      Ok(())
   }

7. 在lib.rs中将您的驱动程序crate标记为no_std：

   #![no_std]

8. 在lib.rs中添加一个panic处理程序：

   #[cfg(not(test))]
   extern crate wdk_panic;
   

9. 可选：在lib.rs中添加一个全局分配器：

   #[cfg(not(test))]
   use wdk_alloc::WDKAllocator;
   
   #[cfg(not(test))]
   #[global_allocator]
   static GLOBAL_ALLOCATOR: WDKAllocator = WDKAllocator;

   只有当您想要能够使用Rust标准库中的alloc模块时，才需要这样做。您也可以自由使用自己的全局分配器实现。

10. 在lib.rs中添加一个DriverEntry：

use wdk_sys::{
   DRIVER_OBJECT,
   NTSTATUS,
   PCUNICODE_STRING,
};

#[export_name = "DriverEntry"] // WDF期望一个名为DriverEntry的符号
pub unsafe extern "system" fn driver_entry(
   driver: &mut DRIVER_OBJECT,
   registry_path: PCUNICODE_STRING,
) -> NTSTATUS {
   0
}

11. 添加一个Makefile.toml：

extend = "target/rust-driver-makefile.toml"

[env] CARGO_MAKE_EXTEND_WORKSPACE_MAKEFILE = true

[config] load_script = ''' #!@rust //! cargo //! [dependencies] //! wdk-build = "0.2.0" //! #![allow(unused_doc_comments)]

wdk_build::cargo_make::load_rust_driver_makefile()? '''

12. 添加一个与你的 `cdylib` crate 名称相匹配的 inx 文件。

13. 构建驱动程序：

   ```pwsh
   cargo make

一个签名的驱动程序包，包括 WDRLocalTestCert.cer 文件，将会生成在 target/<Cargo profile>/package 目录下。如果指定了特定的目标架构，驱动程序包将会生成在 target/<target architecture>/<Cargo profile>/package 目录下。

Cargo Make

cargo-make 用于促进使用 windows-drivers-rs 的构建，包括执行构建后的驱动程序打包步骤。

要执行默认操作（构建和打包驱动程序）：

cargo make default

执行默认任务时，仅使用 cargo make 也可以，因为 default 任务是默认的。

参数转发

windows-drivers-rs 扩展了 cargo make 以将特定参数转发到底层的 cargo 命令。为了指定要转发的参数，必须在明确指定 cargo-make 任务名称之后提供这些参数（即不支持省略 default 任务的名称）。

示例

针对特定目标：

cargo make default --target <TARGET TRIPLE>

针对发布构建：

cargo make default --release 或 cargo make default --profile release

指定特定功能：

cargo make default --features <FEATURES>

指定特定的 Rust 工具链：

cargo make default +<TOOLCHAIN>

显示帮助并查看支持转发给 Cargo 的完整 CLI 参数列表：

cargo make help

驱动程序包签名验证

可以将 WDK_BUILD_ENABLE_SIGNTOOL_VERIFY cargo-make 环境变量设置为 true 以启用处理生成的 .sys 和 .cat 文件签名验证的任务。signtool verify 要求将证书安装在 受信任的根证书颁发机构 中才能进行此验证。默认情况下不启用这些任务，因为 WDR 的默认行为是使用生成的测试证书进行签名。考虑到在个人开发机器上安装自己的根证书的安全隐患，这些测试证书通常只安装在专门用于测试驱动程序的计算机的 受信任的根证书颁发机构 中。

如果你理解这些隐患，并且已安装测试证书，那么你可以按如下方式验证签名：

cargo make --env WDK_BUILD_ENABLE_SIGNTOOL_VERIFY=true

Crates.io 发布策略

合并到主分支的每次更改后都不会向 crates.io 发布。只有在社区要求时，或者当 windows-drivers-rs 团队认为推送发布有足够价值时，才会进行发布。

商标声明

商标 本项目可能包含项目、产品或服务的商标或标志。Microsoft 商标或标志的授权使用必须遵循 Microsoft 的商标和品牌准则。在本项目的修改版本中使用 Microsoft 商标或标志不得引起混淆或暗示 Microsoft 赞助。任何第三方商标或标志的使用都受制于这些第三方的政策。