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: 直接 FFI 绑定到 Windows 开发套件 (WDK) 中可用的 API。这包括从 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 Discussions论坛作为与社区互动的主要形式！

支持的配置

此项目考虑到支持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-安装LLVM.LLVM
    • 请确保选择GUI选项以将LLVM添加到PATH

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

  • cargo安装 --锁定cargo-make --无默认功能 --功能tls-native

• 使用WDK构建程序还需要处于有效的WDK环境中。推荐的执行方式是进入eWDK开发提示符

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

此存储库中的crate可以在crates.io中找到，但请注意支持的配置中概述的当前限制。如果您需要支持不同的配置，请尝试克隆此存储库并使用路径依赖

1. 创建一个新的Cargo包，并使用lib crate

   cargo new <driver_name> --lib
   

2. 在Cargo.toml中添加对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 # optional setting to enable Link Time Optimizations
   
   [profile.release]
   panic = "abort"
   lto = true # optional setting to enable Link Time Optimizations
   

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 expects a symbol with the name 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 包名匹配的 inx 文件。

13. 构建驱动程序

cargo make

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

Cargo Make

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

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

cargomake default

在执行默认任务时，只需 cargo make，使用 make 也可以工作，因为默认任务已经隐含在其中。

参数转发

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

示例

对于特定的目标

cargomake default --target <TARGET TRIPLE>

对于发布构建

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

指定特定的功能

cargomake default --feature <FUNCTIONS>

指定特定的 Rust 工具链

cargomake default +<TOOLCHAIN>

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

cargomake help

驱动程序包签名验证

WDK_BUILD_ENABLE_SIGNTOOL_VERIFY cargo-make 环境变量 可以设置为 true 以启用处理生成的 .sys 和 .cat 文件签名验证的任务。 signtool verify 需要证书已安装为 Trusted Root Certification Authorities 的一部分，以便验证功能正常。这些任务默认不启用，因为 WDR 的默认行为是使用生成的测试证书进行签名。这些测试证书通常只安装到用于测试驱动程序的专用计算机上的 Trusted Root Certification Authorities，而不是个人开发机器，因为安装您自己的根证书具有安全影响。

如果您理解这些影响，并且已安装测试证书，则可以按以下方式验证签名

cargo make --env WDK_BUILD_ENABLE_SIGNTOOL_VERIFY=true

Crates.io 发布策略

并非每次将更改合并到主分支后都会在crates.io进行发布。只有在社区请求或当windows-drivers-rs团队认为发布具有足够价值时才会进行发布。

商标声明

商标本项目中可能包含项目、产品或服务的商标或徽标。Microsoft商标或徽标的授权使用必须遵循Microsoft的商标和品牌指南。在此项目的修改版本中使用Microsoft商标或徽标不得引起混淆或暗示Microsoft的赞助。任何第三方商标或徽标的用途均受该第三方政策约束。