1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
//! An idiomatic Rust mutex type for Windows kernel driver development.
//!
//! The crate will safely check IRQL before doing operations which would cause a STOP CODE of
//! IRQL NOT LESS OR EQUAL (**except for RAII dropping of scoped Mutex Guards**).
//! In those cases, the API will return an error of the internal type `DriverMutexError`.
//!
//! This crate 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 for Windows Rust Kernel Driver
//! development.
//!
//! # Additional features:
//!
//! - `debug`: Enabling this feature will print debug messages to an attached debugger or kernel message viewer when an IRQL error occurs.
//!
//! # 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.
//!
//! # Tests
//!
//! Tests have been conducted on public modules.
//!
//! No tests are included in the crate. Tests have been conducted on
//! [another of my projects](https://github.com/0xflux/Sanctum/blob/main/driver/src/mutex_test.rs)
//! in a dedicated test module; but a new repo
//! will be created specifically for testing this crate which can be built as a driver.
//!
//! <section class="warning">
//! 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.
//!
//! This is licenced with an MIT Licence, conditions can be found in LICENCE in the crate GitHub repository.
//! </section>
// mod fast_mutex;