windows-drivers-rs

此仓库是 Rust 包的集合，允许开发者在 Rust 中开发 Windows 驱动程序。目的是支持 WDM 和 WDF 驱动程序开发模型。此仓库包含以下包

• wdk-build: 一个库，用于配置 Cargo 构建脚本来生成绑定并链接 WDK（Windows 驱动程序包）。虽然此包旨在对不同版本的 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 的直接绑定交互。此包通过 wdk-sys 重新导出，并且通常不需要直接依赖 wdk-macros

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

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

支持配置

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

入门指南

构建要求

• 通过 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. 使用库 crate 创建新的 Cargo 包

   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
}

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()?
'''

cargo make

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

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

cargomake default

在执行默认任务时，只需cargo make，由于默认任务已经隐含，因此这种方式也适用。

参数传递

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

示例

针对特定目标

cargomake default --target <目标三元组>

针对发布构建

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

指定特定功能

cargomake default --feature <功能>

指定特定的 Rust 工具链

cargomake default +<工具链>

显示帮助并查看传递给 Cargo 的完整 CLI 参数列表

cargomake 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团队认为推动发布具有足够价值时才会进行发布。

商标声明

商标声明 本项目可能包含项目、产品或服务的商标或徽标。使用微软的商标或徽标需遵守并遵循微软的商标及品牌指南。在修改本项目版本中使用微软的商标或徽标不得引起混淆或暗示微软赞助。任何第三方商标或徽标的用途均需遵守相关第三方的政策。