{"id":23627413,"url":"https://github.com/0xflux/wdk-mutex","last_synced_at":"2025-06-13T07:34:28.979Z","repository":{"id":269837431,"uuid":"908620332","full_name":"0xflux/wdk-mutex","owner":"0xflux","description":"An idiomatic Rust mutex type for Windows kernel driver development. ","archived":false,"fork":false,"pushed_at":"2025-01-08T19:37:11.000Z","size":120933,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-21T00:47:13.840Z","etag":null,"topics":["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"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/wdk-mutex","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xflux.png","metadata":{"files":{"readme":"Readme.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-26T14:21:51.000Z","updated_at":"2025-05-18T07:47:15.000Z","dependencies_parsed_at":"2025-04-09T21:32:08.100Z","dependency_job_id":"4eeb5587-29de-4dcc-9d30-1869d12682da","html_url":"https://github.com/0xflux/wdk-mutex","commit_stats":null,"previous_names":["0xflux/wdk-mutex","0xflux/wdk_mutex"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/0xflux/wdk-mutex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xflux%2Fwdk-mutex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xflux%2Fwdk-mutex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xflux%2Fwdk-mutex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xflux%2Fwdk-mutex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xflux","download_url":"https://codeload.github.com/0xflux/wdk-mutex/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xflux%2Fwdk-mutex/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259602679,"owners_count":22883031,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2024-12-27T23:59:14.474Z","updated_at":"2025-06-13T07:34:28.403Z","avatar_url":"https://github.com/0xflux.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# wdk-mutex\n\nAn idiomatic Rust mutex type for Windows kernel driver development.\n\nTo use this crate, simply:\n\n```\ncargo add wdk-mutex\n```\n\n**See the sections below for examples**. This crate assumes you already have a Rust Windows Driver Kit project\nusing the Microsoft [windows-drivers-rs](https://github.com/microsoft/windows-drivers-rs) crate. You will\nnot be able to use this crate unless you are in a wdk development environment, setup steps outlined on\ntheir repository.\n\nThis crate checks IRQL when acquiring and releasing the mutex, returning an error if IRQL is too high. See the crate documentation for details.\n\n`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 \nKernel Driver development.\n\nAs 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.\n\nAll tests are carried out at [wdk_mutex_tests](https://github.com/0xflux/wdk_mutex_tests), \na separate repository which is built as a driver to test all functionality of the `wdk-mutex` crate. If you wish to run the tests\nyourself, or contribute, please check that repository.\n\nThis is licenced with an MIT Licence, conditions can be found in LICENCE in the crate GitHub repository.\n\n## Features:\n\n**Global mutex tracking:**\n\nThe `wdk-mutex` crate allows you to easily create, track, and use mutexes for a Windows Kernel Driver across all threads and \ncallbacks. This improves developer ergonomics in creating, tracking, dropping etc mutexes throughout your drivers codebase. \n\nTo use it, the `Grt` (Global Reference Tracker) module will allocate a safe reference tracker, allowing you to then register a `T` to be protected by a Mutex. This\nregistration takes a `\u0026'static str` which is the key for the Mutex object. At runtime, you are able to safely retrieve the mutex and operate\non the inner T across threads and callbacks.\n\nThe `Grt` will also **prevent memory leaks** as it implements a `destroy()` function which you call only once, and all data tracked by the `Grt` will be deallocated, \nmaking life much easier tracking global static data in a driver.\n\n**KMUTEX:** \n\nThe `wdk-mutex` crate supports acquiring a KMUTEX. The type `Kmutex\u003cT\u003e` provides mutually exclusive access\nto the inner type T allocated through this crate in the non-paged pool. All data required to initialise the \nKMutex 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.\n\nAccess to the `T` within the `KMutex` can be done through calling `lock`, similar to the Rust std Mutex.\n\nAs the `KMutex` is designed to be used in the Windows Kernel, with the Windows `wdk` crate, the lifetimes of \nthe `KMutex` must be considered by the caller. See **examples** below for usage.\n\n**FAST_MUTEX:** \n\nAs well as a `KMUTEX`, `wdk-mutex` also supports the use of acquiring a [FAST_MUTEX](https://learn.microsoft.com/en-us/windows-hardware/drivers/kernel/eprocess). Locking a FAST_MUTEX is faster than locking a `KMUTEX`.\n\n# Examples\n\nTo see a real project using this, check my [Sanctum driver](https://github.com/0xflux/Sanctum). Alternatively, check the [tests repo](https://github.com/0xflux/wdk_mutex_tests) for this crate which tests features which will give you inspiration as to how the mutexes can be used. I would recommend utilising the `Grt` \nmodule for globally accessible mutexes.\n\n## Locally scoped mutex:\n\n```rust\n{\n    let mtx = KMutex::new(0u32).unwrap();\n    let lock = mtx.lock().unwrap();\n\n    // If T implements display, you do not need to dereference the lock to print.\n    println!(\"The value is: {}\", lock);\n} // Mutex will become unlocked as it is managed via RAII \n```\n\n## Global scope via wdk-mutex Grt:\n\nTo use mutexes across your driver at runtime with ease:\n\n```rust\n// Initialise the mutex on DriverEntry\n\n#[export_name = \"DriverEntry\"]\npub unsafe extern \"system\" fn driver_entry(\n    driver: \u0026mut DRIVER_OBJECT,\n    registry_path: PCUNICODE_STRING,\n) -\u003e NTSTATUS {\n    if let Err(e) = Grt::init() {\n        println!(\"Error creating Grt!: {:?}\", e);\n        return STATUS_UNSUCCESSFUL;\n    }\n\n    // ...\n    my_function();\n}\n\n\n// Register a new Mutex in the `Grt` of value 0u32:\n\npub fn my_function() {\n    Grt::register_fast_mutex(\"my_test_mutex\", 0u32);\n}\n\nunsafe extern \"C\" fn my_thread_fn_pointer(_: *mut c_void) {\n    let my_mutex = Grt::get_fast_mutex::\u003cu32\u003e(\"my_test_mutex\");\n    if let Err(e) = my_mutex {\n        println!(\"Error in thread: {:?}\", e);\n        return;\n    }\n\n    let mut lock = my_mutex.unwrap().lock().unwrap();\n    *lock += 1;\n}\n\n\n// Destroy the Grt to prevent memory leak on DriverExit\n\nextern \"C\" fn driver_exit(driver: *mut DRIVER_OBJECT) {\n    unsafe {Grt::destroy()};\n}\n```\n\n# Stability\n\nThis crate has been built and tested with **nightly-2024-12-21**. Stability outside of nightly versions\nstipulated here are considered undefined.\n\nThe crate has been tested on a Windows 11 image as a driver. No testing of other Windows versions have \nbeen conducted.\n\n# Planned updates\n\n## Critical Sections:\n\nAn idiomatic implementation for entering and leaving a mutex critical section where no underlying \nT is protected.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xflux%2Fwdk-mutex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xflux%2Fwdk-mutex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xflux%2Fwdk-mutex/lists"}