Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/0xflux/wdk-mutex

An idiomatic Rust mutex type for Windows kernel driver development.
https://github.com/0xflux/wdk-mutex

driver driver-mutex kernel kernel-driver kernel-mutex kerrnel-mutex kmutex microsoft mutex rust thread-safety wdk wdk-driver winapi windows windows-driver windows-driver-kit

Last synced: 1 day ago
JSON representation

An idiomatic Rust mutex type for Windows kernel driver development.

Awesome Lists containing this project

README 

        
# wdk-mutex



An idiomatic Rust mutex type for Windows kernel driver development.



To use this crate, simply:



```

cargo add wdk-mutex

```



**See the sections below for examples**. This crate assumes you already have a Rust Windows Driver Kit project

using the Microsoft [windows-drivers-rs](https://github.com/microsoft/windows-drivers-rs) crate. You will

not be able to use this crate unless you are in a wdk development environment, setup steps outlined on

their repository.



This crate checks IRQL when acquiring and releasing the mutex, returning an error if IRQL is too high. See the crate documentation for details.



`wdk-mutex` is a work in progress to implement additional mutex types and functionality as required. Contributions, issues, and discussions are welcome. This crate is **NOT** affiliated with the WDK crates provided by Microsoft, but is designed to work with them and their ecosystem for Windows Rust 

Kernel Driver development.



As this crate integrates into the wdk ecosystem, Microsoft stipulate: This project is still in early stages of development and is not yet recommended for production use.



All tests are carried out at [wdk_mutex_tests](https://github.com/0xflux/wdk_mutex_tests), 

a separate repository which is built as a driver to test all functionality of the `wdk-mutex` crate. If you wish to run the tests

yourself, or contribute, please check that repository.



This is licenced with an MIT Licence, conditions can be found in LICENCE in the crate GitHub repository.



## Stability



This crate has been built and tested with **nightly-2024-12-21**. Stability outside of nightly versions

stipulated here are considered undefined.



The crate has been tested on a Windows 11 image as a driver. No testing of other Windows versions have 

been conducted.



## Features:



**KMUTEX:** 



The `wdk-mutex` crate supports acquiring a KMUTEX. The type `Kmutex` provides mutually exclusive access

to the inner type T allocated through this crate in the non-paged pool. All data required to initialise the 

KMutex is allocated in the non-paged pool and as such is safe to pass stack data into the type as it will not go out of scope.



Access to the `T` within the `KMutex` can be done through calling `lock`, similar to the Rust std Mutex.



As the `KMutex` is designed to be used in the Windows Kernel, with the Windows `wdk` crate, the lifetimes of 

the `KMutex` must be considered by the caller. See **examples** below for usage.



# Examples



## Locally scoped mutex:



```rust

{

    let mtx = KMutex::new(0u32).unwrap();

    let lock = mtx.lock().unwrap();



    // If T implements display, you do not need to dereference the lock to print.

    println!("The value is: {}", lock);

} // Mutex will become unlocked as it is managed via RAII 

```



## Global scope via static pointer:



A future release is planned to make this process more ergonomic.



```rust

pub static HEAP_MTX_PTR: AtomicPtr> = AtomicPtr::new(null_mut());



fn my_fn() {

    let heap_mtx = Box::new(KMutex::new(0u32).unwrap());

    let heap_mtx_ptr = Box::into_raw(heap_mtx);

    HEAP_MTX_PTR.store(heap_mtx_ptr, Ordering::SeqCst);



    // spawn some system threads

    r _ in 0..3 {

        let mut thread_handle: HANDLE = null_mut();

        let status = unsafe {

            PsCreateSystemThread(

                &mut thread_handle, 

                0, 

                null_mut::(), 

                null_mut(),

                null_mut::(), 

                Some(callback_fn), 

                null_mut(),

            )

        };

        println!("[i] Thread status: {status}");

    }

}



unsafe extern "C" fn callback_fn(_: *mut c_void) {

    for _ in 0..50 {

        let p = HEAP_MTX_PTR.load(Ordering::SeqCst);

        if !p.is_null() {

            let p = unsafe { &*p };

            let mut lock = p.lock().unwrap();

            println!("Got the lock before change! {}", *lock);

            *lock += 1;

            println!("After the change: {}", *lock);

        }

    }

}



// IMPORTANT ensure the KMutex in the static is properly dropped to clean memory

extern "C" fn driver_exit(driver: *mut DRIVER_OBJECT) {

    let ptr: *mut KMutex = HEAP_MTX_PTR.load(Ordering::SeqCst);

    if !ptr.is_null() {

        unsafe {

            // RAII will kick in here to deallocate our memory

            let _ = Box::from_raw(ptr);

        }

    }

}

```



# Planned updates



## Global interface:



A future addition is planned which will make the API more flexible for dynamically managing globally 

available mutexes to somewhat reduce the overhead required to use this crate.



## Critical Sections:



An idiomatic implementation for entering and leaving a mutex critical section where no underlying 

T is protected.



## FAST_MUTEX



An idiomatic implementation for FAST_MUTEX.



The next planned release will add Critical Section behaviour, where you do not want to wrap a generic T in a mutex (similar to std::mutex), but you want a section to be a critical section nonetheless.



Please note that each planned feature will be introduced gradually, and might undergo changes based on community feedback. 



I welcome any contributions or suggestions to improve functionality, documentation, and compatibility.