add kernel sync primitives

[J.K Lee (ntoskrnl7)]

Summary

Adds safe Rust synchronization wrappers for common kernel-mode shared/exclusive locks:

• wdk::sync::RwLock<T> backed by ERESOURCE
• wdk::sync::PushLock<T> backed by EX_PUSH_LOCK
• wdk::sync::RwSpinLock<T> backed by EX_SPIN_LOCK

The wrappers provide RAII read/write guards, document IRQL constraints, and expose get_mut for exclusive mutable access without locking.

Details

RwLock allocates the backing ERESOURCE separately so the kernel object has a stable address for its lifetime. PushLock wraps the modern ExAcquirePushLock*Ex APIs. RwSpinLock includes normal acquire methods that restore IRQL on drop plus *_at_dpc_level methods for callers already at DISPATCH_LEVEL.

The WDM sample driver now demonstrates all three wrappers. WDM config tests cover guard access and get_mut, with matching wdk-sys test stubs for the kernel routines used by these wrappers.

Validation

• cargo +1.91.0 check -p wdk
• cargo +1.91.0 test --manifest-path tests\config-wdm\Cargo.toml
• cargo +1.91.0 build --manifest-path examples\sample-wdm-driver\Cargo.toml
• cargo +1.91.0 clippy -p wdk --all-targets -- -D warnings
• cargo +1.91.0 clippy --manifest-path tests\config-wdm\Cargo.toml --all-targets -- -D warnings
• cargo +1.91.0 clippy --manifest-path examples\sample-wdm-driver\Cargo.toml --all-targets -- -D warnings -A clippy::multiple-crate-versions

The sample driver clippy command allows multiple-crate-versions because the current dependency graph includes windows-sys through both fs4 and build-time dependencies.

[J.K Lee (ntoskrnl7)]

@microsoft-github-policy-service agree

[Copilot]

Pull request overview

This PR adds a new wdk::sync module providing safe, RAII-based wrappers around common kernel-mode shared/exclusive synchronization primitives for WDM/KMDF, along with WDM sample usage and test coverage via wdk-sys test stubs.

Changes:

• Introduces wdk::sync::{RwLock, PushLock, RwSpinLock} with guard types and IRQL/critical-region handling.
• Updates wdk-sys test stubs and WDM config tests to enable exercising these primitives in unit tests.
• Extends the sample WDM driver to demonstrate the new locks and improves UNICODE_STRING handling.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/config-wdm/tests/rw_lock_tests.rs	Adds WDM config tests covering guard access and get_mut for the new sync wrappers.
tests/config-wdm/Cargo.toml	Adds dev-deps on wdk/wdk-sys(test-stubs) and a nightly feature passthrough.
tests/config-wdm/Cargo.lock	Updates lockfile to include the new dependency graph (lockfile v4).
examples/sample-wdm-driver/src/lib.rs	Demonstrates RwLock, PushLock, and RwSpinLock; refines registry path parsing.
crates/wdk/src/sync/rw_spin_lock.rs	Implements RwSpinLock<T> backed by EX_SPIN_LOCK with IRQL-restoring guards.
crates/wdk/src/sync/rw_lock.rs	Implements RwLock<T> backed by heap-allocated ERESOURCE with read/write guards and try-acquire.
crates/wdk/src/sync/push_lock.rs	Implements PushLock<T> backed by EX_PUSH_LOCK with critical-region-managed guards.
crates/wdk/src/sync/mod.rs	Adds module-level docs and re-exports for the new sync primitives.
crates/wdk/src/lib.rs	Exposes wdk::sync (WDM/KMDF only) and enables alloc at crate root for those targets.
crates/wdk-sys/src/test_stubs.rs	Adds stubs for the kernel routines needed to link/run tests for the new wrappers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated no new comments.

[J.K Lee (ntoskrnl7)]

Addressed the Copilot review feedback and folded the cleanup into the existing feature commit.

• Split the RwLock::drop unsafe operations into separate unsafe blocks.
• Replaced the guard marker with a private NotSend marker based on PhantomData<alloc::rc::Rc<()>> instead of negative Send impls, since negative impls are not stable Rust.
• Clarified the PushLock and RwSpinLock WDK usage constraints in the public docs.
• Renamed the WDM sync test file to sync_tests.rs now that it covers all three sync wrappers.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 6 comments.

[J.K Lee (ntoskrnl7)]

Addressed the latest review feedback in f2f74d4.

• Changed all newly added push-lock and EX_SPIN_LOCK test stubs to extern system so their ABI matches the WDK exports, including 32-bit Windows targets.
• Added config-WDM coverage for RwSpinLock::read_at_dpc_level and write_at_dpc_level, including guard dereference/mutation and the drop/release paths.
• git diff --check passes.

I could not run cargo fmt/test/clippy locally because the available environment does not have a Rust/Cargo toolchain installed; CI should provide the executable verification.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

crates/wdk/src/sync/rw_spin_lock.rs:97

• The safety contract for read_at_dpc_level says the caller must already be at DISPATCH_LEVEL, but it should also require that IRQL remains at DISPATCH_LEVEL until the guard is dropped (since Drop uses ExReleaseSpinLock*FromDpcLevel). Please document this explicitly to prevent safe-looking misuse where IRQL is lowered before the guard is dropped.

This issue also appears on line 134 of the same file.

    /// Lock this `RwSpinLock` with shared read access at `DISPATCH_LEVEL`.
    ///
    /// # Safety
    ///
    /// The caller must already be running at `DISPATCH_LEVEL`. The returned
    /// guard will not restore IRQL when it is dropped.
    #[must_use]
    pub unsafe fn read_at_dpc_level(&self) -> RwSpinLockReadGuard<'_, T> {

crates/wdk/src/sync/rw_spin_lock.rs:141

• Similarly to read_at_dpc_level, the safety docs for write_at_dpc_level should state that the caller must remain at DISPATCH_LEVEL for the entire lifetime of the returned guard (until it is dropped), because the Drop path releases the lock using the *FromDpcLevel routine.

    /// Lock this `RwSpinLock` with exclusive write access at `DISPATCH_LEVEL`.
    ///
    /// # Safety
    ///
    /// The caller must already be running at `DISPATCH_LEVEL`. The returned
    /// guard will not restore IRQL when it is dropped.
    #[must_use]
    pub unsafe fn write_at_dpc_level(&self) -> RwSpinLockWriteGuard<'_, T> {

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated no new comments.

Suppressed comments (3)

Previously missed (2) — in code that hasn't changed since the last review.

crates/wdk-sys/src/test_stubs.rs:20

• The added exported kernel-stub symbols (ExInitializeResourceLite, ExAcquire*, etc.) are UpperCamelCase, which triggers Rust's non_snake_case lint. Adding a module-level #![allow(non_snake_case)] keeps builds/lints clean while still matching the required kernel symbol names.

//!   - if used with a driver bin crate you may need to cfg gate your
//!     `DriverEntry` since these stubs provide one
//!

crates/wdk/src/sync/rw_lock.rs:95

• RwLock::read uses assert!(acquired). In kernel-mode builds this is a panic path in both debug and release, even though the WDK contract for wait = true is that acquisition should not fail. Consider downgrading this to debug_assert! to avoid a hard failure in release builds.

This issue also appears on line 110 of the same file.

    pub fn read(&self) -> RwLockReadGuard<'_, T> {
        let acquired = self.acquire_shared(true);
        assert!(acquired);

crates/wdk/src/sync/rw_lock.rs:113

• RwLock::write uses assert!(acquired). As with read(), this panics in release builds; using debug_assert! keeps the invariant check in debug builds without introducing a kernel panic path in release.

    pub fn write(&self) -> RwLockWriteGuard<'_, T> {
        let acquired = self.acquire_exclusive(true);
        assert!(acquired);

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated no new comments.