windows-drivers-rs

This repo is a collection of Rust crates that enable developers to develop Windows Drivers in Rust. It is the intention to support both WDM and WDF driver development models. This repo contains the following crates:

• wdk-build: A library to configure a Cargo build script for binding generation and downstream linking of the WDK (Windows Driver Kit). While this crate is written to be flexible with different WDK releases and different WDF version, it is currently only tested for NI eWDK, KMDF 1.33, UMDF 2.33, and WDM Drivers. There may be missing linker options for older DDKs.
• wdk-sys: Direct FFI bindings to APIs available in the Windows Development Kit (WDK). This includes both autogenerated ffi bindings from bindgen, and also manual re-implementations of macros that bindgen fails to generate.
• wdk: Safe idiomatic bindings to APIs available in the Windows Development Kit (WDK)
• wdk-panic: Default panic handler implementations for programs built with WDK
• wdk-alloc: alloc support for binaries compiled with the Windows Development Kit (WDK)
• wdk-macros: A collection of macros that help make it easier to interact with wdk-sys's direct bindings. This crate is re-exported via wdk-sys and crates should typically never need to directly depend on wdk-macros

To see an example of this repo used to create drivers, see Windows-rust-driver-samples.

Note: This project is still in early stages of development and is not yet recommended for production use. We encourage community experimentation and collaboration through our GitHub Discussions forum!

Supported Configurations

This project was built with support of WDM, KMDF, and UMDF drivers in mind, as well as Win32 Services. This includes support for all versions of WDF included in WDK 22H2 and newer. Currently, the crates available on crates.io only support KMDF v1.33, but bindings can be generated for everything else by cloning windows-drivers-rs and modifying the config specified in build.rs of wdk-sys. Crates.io support for other WDK configurations is planned in the near future.

Repo Layout

• crates: Contains all the main crates that are a part of the Cargo workspace.
• examples: Contains workspace-level examples. These examples consist of different types of minimal Windows drivers (ie. WDM, KMDF, UMDF).
• tests: Contains workspace-level tests, including tests for metadata-based wdk configuration in packages and workspaces.

Note:: Since the workspace level examples and tests use different WDK configurations, and WDR only supports one WDK configuration per workspace, the workspace-level examples and tests folder are excluded from the repository root's Cargo manifest.

Getting Started

Build Requirements

• Binding generation via bindgen requires libclang. The easiest way to acquire this is via winget

  • winget install -i LLVM.LLVM --version 17.0.6 --force
    • Ensure you select the GUI option to add LLVM to the PATH
    • LLVM 18 has a bug that causes bindings to fail to generate for ARM64. Continue using LLVM 17 until LLVM 19 comes out with the fix. See this for more details.

• To execute post-build tasks (ie. inf2cat, infverif, etc.), cargo make is used

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

• Building programs with the WDK also requires being in a valid WDK environment. The recommended way to do this is to enter an eWDK developer prompt

Adding windows-drivers-rs to Your Driver Package

The crates in this repository are available from crates.io, but take into account the current limitations outlined in Supported Configurations. If you need to support a different config, try cloning this repo and using path dependencies

1. Create a new Cargo package with a lib crate:

   cargo new <driver_name> --lib
   

2. Add dependencies on windows-drivers-rs crates:

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

3. Set the crate type to cdylib by adding the following snippet to Cargo.toml:

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

4. Add a wdk metadata section and configure the wdk for your use case. This also lets the cargo-make tasks know that the package is a driver and that the driver packaging steps need to run.

   UMDF Example:

   [package.metadata.wdk.driver-model]
   driver-type = "UMDF"
   umdf-version-major = 1
   target-umdf-version-minor = 33
   

5. For Kernel Mode crates (ex. KMDF drivers, WDM drivers): Set crate panic strategy to abort in Cargo.toml:

   [profile.dev]
   panic = "abort"
   
   [profile.release]
   panic = "abort"
   

6. Create a build.rs and add the following snippet:

   fn main() -> Result<(), wdk_build::ConfigError> {
      wdk_build::configure_wdk_binary_build()
   }
   

7. For Kernel Mode crates (ex. KMDF drivers, WDM drivers): Mark your driver crate as no_std in lib.rs:

   #![no_std]
   

8. For Kernel Mode crates (ex. KMDF drivers, WDM drivers): Add a panic handler in lib.rs:

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

9. For Kernel Mode crates (ex. KMDF drivers, WDM drivers): Add an optional global allocator in lib.rs:

This is the beginning of the README. Read the rest at the original. Read the full README ↗