Skip to content

AGENTS.md

Latest commit

 

History

History
94 lines (65 loc) · 4.63 KB

AGENTS.md

File metadata and controls

94 lines (65 loc) · 4.63 KB

Copilot Instructions for windows-drivers-rs

Overview

Rust crates for developing Windows Drivers (WDM, KMDF, UMDF). The workspace only includes the library crates under crates/; examples and tests are excluded from the root workspace because each requires a different WDK configuration (only one WDK config per Cargo build graph is supported).

Architecture

Crate layering (bottom → top):

  1. wdk-build — Build-time crate. Configures cargo build scripts for WDK binding generation, linker settings, and cargo-make task generation. Also contains the rust-driver-makefile.toml that downstream driver packages extend.
  2. wdk-sys (no_std) — Raw FFI bindings auto-generated by bindgen, plus hand-written macro re-implementations where bindgen fails. Uses custom cfg flags (driver_model__driver_type, driver_model__kmdf_version_major, etc.) set by wdk-build to conditionally compile for WDM/KMDF/UMDF.
  3. wdk-macros — Proc-macro crate consumed only through wdk-sys re-exports. Versioned in lockstep with wdk-sys (enforced by CI version-checks.yaml).
  4. wdk — Safe idiomatic Rust wrappers around wdk-sys. Conditionally no_std for WDM/KMDF; std-capable for UMDF.
  5. wdk-alloc — Global allocator (WdkAllocator) for kernel-mode crates needing alloc.
  6. wdk-panic — Default panic handlers for WDK binaries.
  7. cargo-wdk — Cargo subcommand for building and packaging driver projects.

Key design patterns:

  • Conditional compilation via custom cfg flags (not Cargo features) distinguishes driver types. These flags are emitted by wdk-build during the build script phase.
  • wdk-sys has feature flags for optional WDK subsystem bindings: gpio, hid, spb, storage, usb, parallel-ports.
  • Some crates expose a nightly feature for functionality gated behind unstable Rust features.

Build, Test, and Lint

Requires an eWDK developer prompt and LLVM 17 on PATH for bindgen.

Build

cargo build --locked --all-features

Test

# Full suite
cargo test --locked --all-features

# Single test
cargo test --locked --all-features <test_name>

# Nightly-only tests
cargo +nightly test --locked --features nightly

cargo-expand v1.0.85 is required for macrotest/trybuild-based tests. Switching between stable/nightly toolchains requires deleting cached test artifacts under target/*/tests/ to avoid stale trybuild/macrotest caches.

Lint

# Clippy (warnings are denied via RUSTFLAGS=-Dwarnings)
cargo clippy --locked --all-features --all-targets -- -D warnings

# Formatting (requires nightly for unstable rustfmt options)
cargo +nightly fmt --all -- --check

# TOML formatting
taplo fmt --check --diff

# Cargo.toml dependency sorting
cargo sort -w -g -n --check

# Spelling
typos

# Security audit
cargo audit --deny warnings

# Unused dependencies
cargo machete --skip-target-dir

# Docs build
cargo doc --locked --all-features

Pre-commit (runs everything)

cargo make wdk-pre-commit-flow

Code Conventions

  • Unsafe discipline: unsafe_op_in_unsafe_fn is forbidden at workspace level. Every unsafe block must have exactly one unsafe operation (multiple_unsafe_ops_per_block = "forbid") and a // SAFETY: comment (undocumented_unsafe_blocks = "forbid"). Unnecessary safety docs are also forbidden.
  • FFI naming: Bindings in wdk-sys retain their original C names and style (e.g., PascalCase functions). Safe Rust wrappers in wdk follow Rust naming conventions (RFC 430).
  • Formatting: rustfmt uses nightly-only unstable options (see rustfmt.toml). Import grouping is StdExternalCrate, granularity is Crate.
  • Lints: Clippy all is deny, pedantic/nursery/cargo are warn. Most workspace members inherit [lints] workspace = true; wdk-sys, wdk-build, wdk-macros, and cargo-wdk define their own [lints] tables instead (Cargo currently does not support both inheriting workspace lints and selectively overriding them per crate).
  • Edition: 2024, MSRV 1.91.0, resolver v3.
  • Static CRT: Enabled globally via .cargo/config.toml (-C target-feature=+crt-static).
  • Spelling: typos is configured in .typos.toml; Windows API identifiers are allowlisted rather than using file-level excludes.
  • TOML: taplo uses CRLF line endings (see taplo.toml).
  • Versioning: wdk-macros and wdk-sys must have identical versions (exact = dependency). This is enforced by the version-checks.yaml CI workflow.