Crates.io | wdk-sys |
lib.rs | wdk-sys |
version | |
source | src |
created_at | 2023-09-11 19:19:51.122946 |
updated_at | 2024-10-02 23:44:25.255357 |
description | Direct bindings to APIs available in the Windows Development Kit (WDK) |
homepage | |
repository | https://github.com/microsoft/windows-drivers-rs |
max_upload_size | |
id | 970035 |
Cargo.toml error: | TOML parse error at line 18, column 1 | 18 | autolib = false | ^^^^^^^ unknown field `autolib`, expected one of `name`, `version`, `edition`, `authors`, `description`, `readme`, `license`, `repository`, `homepage`, `documentation`, `build`, `resolver`, `links`, `default-run`, `default_dash_run`, `rust-version`, `rust_dash_version`, `rust_version`, `license-file`, `license_dash_file`, `license_file`, `licenseFile`, `license_capital_file`, `forced-target`, `forced_dash_target`, `autobins`, `autotests`, `autoexamples`, `autobenches`, `publish`, `metadata`, `keywords`, `categories`, `exclude`, `include` |
size | 0 |
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:
bindgen
, and also manual re-implementations of macros that bindgen fails to generate.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, suggestions and discussions! We will be using our GitHub Discussions forum as the main form of engagement with the community!
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.
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.
Binding generation via bindgen
requires libclang
. The easiest way to acquire this is via winget
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
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
Create a new Cargo package with a lib crate:
cargo new <driver_name> --lib
Add dependencies on windows-drivers-rs
crates:
cd <driver_name>
cargo add --build wdk-build
cargo add wdk wdk-sys wdk-alloc wdk-panic
Set the crate type to cdylib
by adding the following snippet to Cargo.toml
:
[lib]
crate-type = ["cdylib"]
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
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"
Create a build.rs
and add the following snippet:
fn main() -> Result<(), wdk_build::ConfigError> {
wdk_build::configure_wdk_binary_build()
}
For Kernel Mode crates (ex. KMDF
drivers, WDM
drivers): Mark your driver crate as no_std
in lib.rs
:
#![no_std]
For Kernel Mode crates (ex. KMDF
drivers, WDM
drivers): Add a panic handler in lib.rs
:
#[cfg(not(test))]
extern crate wdk_panic;
For Kernel Mode crates (ex. KMDF
drivers, WDM
drivers): Add an optional global allocator in lib.rs
:
#[cfg(not(test))]
use wdk_alloc::WdkAllocator;
#[cfg(not(test))]
#[global_allocator]
static GLOBAL_ALLOCATOR: WdkAllocator = WdkAllocator;
This is only required if you want to be able to use the alloc
modules in the rust standard library.
Add a DriverEntry in lib.rs
:
use wdk_sys::{
PDRIVER_OBJECT,
NTSTATUS,
PCUNICODE_STRING,
};
#[export_name = "DriverEntry"] // WDF expects a symbol with the name DriverEntry
pub unsafe extern "system" fn driver_entry(
driver: PDRIVER_OBJECT,
registry_path: PCUNICODE_STRING,
) -> NTSTATUS {
0
}
Note: In Kernel Mode crates, you can use driver: &mut DRIVER_OBJECT
instead of driver: PDRIVER_OBJECT
.
Add a Makefile.toml
:
extend = "target/rust-driver-makefile.toml"
[config]
load_script = '''
#!@rust
//! ```cargo
//! [dependencies]
//! wdk-build = "0.3.0"
//! ```
#![allow(unused_doc_comments)]
wdk_build::cargo_make::load_rust_driver_makefile()?
'''
Add an inx file that matches the name of your cdylib
crate.
Enable static crt linkage. One approach is to add this to your .cargo/config.toml
:
[build]
rustflags = ["-C", "target-feature=+crt-static"]
Build the driver:
cargo make
A signed driver package, including a WDRLocalTestCert.cer
file, will be generated at target/<Cargo profile>/package
. If a specific target architecture was specified, the driver package will be generated at target/<target architecture>/<Cargo profile>/package
Minimal examples of WDM
, KMDF
, and UMDF
drivers can be found in the examples directory.
cargo-make
is used to facilitate builds using windows-drivers-rs
, including for executing post-build driver packaging steps.
To execute the default action (build and package driver):
cargo make default
When executing the default task, just cargo make
make also works since the default
task is implied.
windows-drivers-rs
extends cargo make
to forward specific arguments to the underlying cargo
commands. In order to specify arguments to forward, they must be provided after explicitly specifying the cargo-make
task name (ie. omitting the name for the default
task is not supported).
For a specific target:
cargo make default --target <TARGET TRIPLE>
For release builds:
cargo make default --release
or cargo make default --profile release
To specify specific features:
cargo make default --features <FEATURES>
To specify a specific rust toolchain:
cargo make default +<TOOLCHAIN>
To display help and see the full list of supported CLI args to forward to Cargo:
cargo make help
The WDK_BUILD_ENABLE_SIGNTOOL_VERIFY
cargo-make environment variable can be set to true
to enable tasks that handle signature verification of the generated .sys
and .cat
files. signtool verify
requires the certificate to be installed as in the Trusted Root Certification Authorities
for this verification to function. These tasks are not enabled by default as the default behavior of WDR
is to sign with a generated test certificate. These test certificates are typically only installed into Trusted Root Certification Authorities
on computers dedicated to testing drivers, and not personal development machines, given the security implications of installing your own root certificates.
If you understand these implications, and have installed the test certificate, then you may validate the signatures as follows:
cargo make --env WDK_BUILD_ENABLE_SIGNTOOL_VERIFY=true
Releases to crates.io are not made after every change merged to main. Releases will only be made when requested by the community, or when the windows-drivers-rs
team believes there is sufficient value in pushing a release.
Trademarks This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.