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]

🔵 Needs a closer look

The DPC-level tests do not verify safety-critical acquire/release routing or saved-IRQL propagation.

Review details

Suppressed comments (1)

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

tests/config-wdm/tests/sync_tests.rs:134

• The spin-lock stubs are all no-ops, so this test only validates value access; it still passes if a guard uses the wrong release routine or fails to propagate the saved IRQL. Since mismatching the normal and DPC-level release paths is safety-critical, make the stubs record each acquire/release variant (and old IRQL) and assert the matching release when both guards are dropped.

• Files reviewed: 11/12 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

Repurposing the legacy no-op alloc feature can break existing allocator-free kernel drivers.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 11/12 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

Unsafe kernel FFI, IRQL transitions, and synchronization invariants warrant final human review.

Review details

• Files reviewed: 11/12 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

The new unsafe kernel synchronization abstractions and IRQL-sensitive behavior warrant final human review despite comprehensive stub-based tests.

Review details

• Files reviewed: 11/12 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

🟡 Changes recommended

The safe RwSpinLock restoring APIs can violate kernel IRQL ordering requirements.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

tests/config-wdm/tests/sync_tests.rs:100

• This test cannot detect missing or mismatched push-lock operations: all four ExAcquire/ExReleasePushLock*Ex stubs are no-ops (crates/wdk-sys/src/test_stubs.rs:261-276), so it would still pass if PushLock::read/write never acquired or released the kernel lock. Please instrument the stubs and assert the shared/exclusive acquire-release sequences, as the RwSpinLock tests do; ideally include the required critical-region enter/leave pairing too.

    fn push_lock_read_and_write_guards_access_value() {
        let lock = PushLock::new(1_u32);

        assert_eq!(*lock.read(), 1);

• Files reviewed: 11/12 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

Kernel synchronization and IRQL-sensitive behavior require final human review.

Review details

• Files reviewed: 11/12 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

Kernel synchronization and IRQL-sensitive unsafe code require final human review.

Review details

• Files reviewed: 11/12 changed files
• Comments generated: 0 new
• Review effort level: Balanced