From 2ec9f2d7e3200ff8f90ae81b9d916499b4a0c314 Mon Sep 17 00:00:00 2001 From: Melvin Wang Date: Wed, 4 Mar 2026 17:56:02 -0800 Subject: [PATCH 1/2] docs: add AGENTS.md and CLAUDE.md for Copilot code review --- AGENTS.md | 189 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 190 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..6ab6432 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,189 @@ +# AGENTS.md + +> Universal instructions for AI coding agents working on this repository. +> See [agents.md](https://agents.md) for the spec. + +## Repository Overview + +Rust ports of Windows driver samples from the official [Windows Driver Samples](https://github.com/microsoft/Windows-driver-samples), using crates from [windows-drivers-rs](https://github.com/microsoft/windows-drivers-rs). All driver crates target `#![no_std]` and compile as `cdylib` for the Windows kernel. + +## Build Commands + +Requires EWDK build environment, Clang (LLVM), and `cargo-make`. + +```shell +# Build all workspace members +cargo build --locked + +# Build and package drivers (stamps INF, creates CAT file in Package/) +cargo make + +# Build a specific driver sample +cargo make --cwd general/echo/kmdf/driver/DriverSync + +# Run the echo test app +cargo run --bin echoapp +cargo run --bin echoapp -- -Async +``` + +## Lint and Formatting + +CI enforces all of these — run before submitting PRs: + +```shell +# Clippy (treats warnings as errors) +cargo clippy --locked --all-targets -- -D warnings + +# Clippy with nightly features +cargo +nightly clippy --locked --all-targets --features nightly -- -D warnings + +# Rust formatting (requires nightly due to unstable rustfmt options) +cargo +nightly fmt --all -- --check + +# TOML formatting +taplo fmt --check --diff + +# Unused dependency detection +cargo machete + +# Security audit +cargo audit --deny warnings + +# Documentation build (warnings are errors via RUSTDOCFLAGS=-D warnings in CI) +cargo doc --locked +``` + +## Architecture + +### Workspace Structure + +The workspace (`Cargo.toml`) contains two categories of driver samples: + +- **`general/`** — Functional driver samples (e.g., `echo/kmdf/driver/DriverSync` is a KMDF echo driver) +- **`tools/`** — Diagnostic/verification drivers (e.g., `dv/kmdf/fail_driver_pool_leak` intentionally leaks memory for Driver Verifier testing) +- **`general/echo/kmdf/exe`** — User-mode test app (`echoapp`) for the echo driver + +### Driver Crate Anatomy + +Each driver crate follows this pattern: + +- **`lib.rs`** — Crate root. `#![no_std]`, clippy lints, module declarations, context structs, `WDF_*_SIZE` constants, and `wdf_declare_context_type!` macro invocations +- **`driver.rs`** — `DriverEntry` (exported as `#[export_name = "DriverEntry"]`, `extern "system"`) and `EvtDriverDeviceAdd` callback +- **`device.rs`** — Device creation, PnP/power callbacks +- **`queue.rs`** — I/O queue initialization and request handling callbacks +- **`build.rs`** — Calls `wdk_build::configure_wdk_binary_build()` +- **`*.inx`** — INF template file for driver installation + +### Key Crate Dependencies (from windows-drivers-rs) + +| Crate | Purpose | +|-------|---------| +| `wdk` | Safe Rust wrappers and macros (`println!`, `paged_code!`, `nt_success`, `wdf::Timer`, `wdf::SpinLock`) | +| `wdk-sys` | Raw FFI bindings to WDK. Use via `call_unsafe_wdf_function_binding!` macro | +| `wdk-alloc` | `WdkAllocator` — kernel-compatible global allocator | +| `wdk-panic` | Kernel-compatible panic handler | +| `wdk-build` | Build-time configuration for driver compilation and `cargo-make` integration | + +## Key Conventions + +### Driver Entry Points + +- `DriverEntry` must use `#[export_name = "DriverEntry"]` and `extern "system"` calling convention +- Place init code in `#[link_section = "INIT"]`; place pageable code in `#[link_section = "PAGE"]` and invoke `paged_code!()` at function entry +- WDF callbacks use `extern "C"` calling convention + +### WDF Function Calls + +All WDF framework function calls go through the `call_unsafe_wdf_function_binding!` macro from `wdk-sys`. These are always `unsafe` blocks: + +```rust +unsafe { + call_unsafe_wdf_function_binding!( + WdfDriverCreate, + driver as PDRIVER_OBJECT, + registry_path, + WDF_NO_OBJECT_ATTRIBUTES, + &raw mut driver_config, + driver_handle_output, + ) +} +``` + +### WDF Structure Sizes + +WDF structs require their `Size` field to be set. The codebase uses const-evaluated `WDF_*_SIZE` constants with compile-time truncation assertions: + +```rust +#[allow( + clippy::cast_possible_truncation, + reason = "size_of::() is known to fit in ULONG due to below const assert" +)] +const WDF_DRIVER_CONFIG_SIZE: ULONG = { + const S: usize = core::mem::size_of::(); + const { assert!(S <= ULONG::MAX as usize) }; + S as ULONG +}; +``` + +### WDF Object Contexts + +Context types are registered using macros from `wdf_object_context.rs`: + +- `wdf_declare_context_type!(MyContext)` — generates `wdf_object_get_my_context` accessor +- `wdf_declare_context_type_with_name!(MyContext, custom_getter_name)` — generates a named accessor +- `wdf_get_context_type_info!(MyContext)` — retrieves the type info pointer for `WDF_OBJECT_ATTRIBUTES.ContextTypeInfo` + +### Kernel Allocator and Panic Handler + +Every driver crate must include both, gated behind `#[cfg(not(test))]`: + +```rust +#[cfg(not(test))] +extern crate wdk_panic; + +#[cfg(not(test))] +use wdk_alloc::WdkAllocator; + +#[cfg(not(test))] +#[global_allocator] +static GLOBAL_ALLOCATOR: WdkAllocator = WdkAllocator; +``` + +### Clippy Configuration + +All driver crates enable strict clippy lints: + +```rust +#![deny(clippy::all)] +#![warn(clippy::pedantic)] +#![warn(clippy::nursery)] +#![warn(clippy::cargo)] +#![allow(clippy::missing_safety_doc)] +``` + +### Nightly Feature Gating + +Crates expose an optional `nightly` feature for unstable Rust capabilities. The feature cascades through `wdk` and `wdk-sys`: + +```toml +[features] +nightly = ["wdk/nightly", "wdk-sys/nightly"] +``` + +### Formatting + +- Rust: Uses nightly `rustfmt` with unstable options (see `rustfmt.toml`): `imports_granularity = "Crate"`, `group_imports = "StdExternalCrate"`, `hex_literal_case = "Upper"`, among others +- TOML: Uses `taplo` with CRLF line endings (`taplo.toml`) + +### Rust Flags + +`-C target-feature=+crt-static` is set in `.cargo/config.toml` and must also be in CI `RUSTFLAGS`. CI also sets `-D warnings` to deny all warnings. + +### Copyright Headers + +Every `.rs` file starts with: + +```rust +// Copyright (c) Microsoft Corporation. +// License: MIT OR Apache-2.0 +``` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md From 6fd7a1aeea5fc00deae8cf206c6b9fd550e8a1ec Mon Sep 17 00:00:00 2001 From: Melvin Wang Date: Fri, 6 Mar 2026 21:02:30 -0800 Subject: [PATCH 2/2] docs: refresh AGENTS.md and CLAUDE.md via copilot init Re-generated AGENTS.md from fresh copilot init output and reset CLAUDE.md to the standard @AGENTS.md shim. --- AGENTS.md | 17 +++++------------ CLAUDE.md | 2 +- 2 files changed, 6 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6ab6432..59381ce 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,9 +1,4 @@ -# AGENTS.md - -> Universal instructions for AI coding agents working on this repository. -> See [agents.md](https://agents.md) for the spec. - -## Repository Overview +# Copilot Instructions Rust ports of Windows driver samples from the official [Windows Driver Samples](https://github.com/microsoft/Windows-driver-samples), using crates from [windows-drivers-rs](https://github.com/microsoft/windows-drivers-rs). All driver crates target `#![no_std]` and compile as `cdylib` for the Windows kernel. @@ -55,9 +50,7 @@ cargo doc --locked ## Architecture -### Workspace Structure - -The workspace (`Cargo.toml`) contains two categories of driver samples: +### Workspace Layout - **`general/`** — Functional driver samples (e.g., `echo/kmdf/driver/DriverSync` is a KMDF echo driver) - **`tools/`** — Diagnostic/verification drivers (e.g., `dv/kmdf/fail_driver_pool_leak` intentionally leaks memory for Driver Verifier testing) @@ -65,9 +58,9 @@ The workspace (`Cargo.toml`) contains two categories of driver samples: ### Driver Crate Anatomy -Each driver crate follows this pattern: +Each driver crate follows this file structure: -- **`lib.rs`** — Crate root. `#![no_std]`, clippy lints, module declarations, context structs, `WDF_*_SIZE` constants, and `wdf_declare_context_type!` macro invocations +- **`lib.rs`** — Crate root with `#![no_std]`, clippy lints, module declarations, context structs, `WDF_*_SIZE` constants, and `wdf_declare_context_type!` macro invocations - **`driver.rs`** — `DriverEntry` (exported as `#[export_name = "DriverEntry"]`, `extern "system"`) and `EvtDriverDeviceAdd` callback - **`device.rs`** — Device creation, PnP/power callbacks - **`queue.rs`** — I/O queue initialization and request handling callbacks @@ -111,7 +104,7 @@ unsafe { ### WDF Structure Sizes -WDF structs require their `Size` field to be set. The codebase uses const-evaluated `WDF_*_SIZE` constants with compile-time truncation assertions: +WDF structs require their `Size` field to be set. Use const-evaluated `WDF_*_SIZE` constants with compile-time truncation assertions: ```rust #[allow( diff --git a/CLAUDE.md b/CLAUDE.md index 43c994c..eef4bd2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1 +1 @@ -@AGENTS.md +@AGENTS.md \ No newline at end of file