wdk_mutex/lib.rs
1//! An idiomatic Rust mutex type for Windows kernel driver development, supporting both `wdm` and `kmdf` drivers.
2//!
3//! ### Installation
4//!
5//! To use this crate, simply:
6//!
7//! ```shell
8//! cargo add wdk-mutex
9//! ```
10//!
11//! In addition to defining either `WDM` or `KMDF` in your `Cargo.toml` as per the instructions given at [windows-drivers-rs](https://github.com/microsoft/windows-drivers-rs/),
12//! you **must** add the following to your `.cargo/config.toml`:
13//!
14//! ```toml
15//! [build]
16//! rustflags = [
17//! "-C", "target-feature=+crt-static",
18//! "--cfg", 'driver_model__driver_type="WDM"' # This line, make sure driver type matches your config, either WDM or KMDF
19//! ]
20//! ```
21//!
22//! As per the above comment, ensure either `driver_model__driver_type="WDM"` for WDM, or `driver_model__driver_type="KMDF"`.
23//!
24//! ### Crate Info
25//!
26//! The crate will safely check IRQL before doing operations which would cause a STOP CODE of
27//! IRQL NOT LESS OR EQUAL (**except for RAII dropping of scoped Mutex Guards**).
28//! In those cases, the API will return an error of the internal type `DriverMutexError`.
29//!
30//! This crate is a work in progress to implement additional mutex types and functionality as required. Contributions, issues,
31//! and discussions are welcome.
32//!
33//! This crate is **not** affiliated with the WDK crates provided by Microsoft, but is designed to work with them for Windows Rust Kernel Driver
34//! development.
35//!
36//! # Tests
37//!
38//! Tests have been conducted on public modules.
39//!
40//! All tests are carried out at [wdk_mutex_tests](https://github.com/0xflux/wdk_mutex_tests),
41//! 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
42//! yourself, or contribute, please check that repository.
43//!
44//! <section class="warning">
45//! As this crate integrates into the wdk ecosystem, Microsoft stipulate: This project is still in early stages of development and
46//! is not yet recommended for production use.
47//!
48//! This is licenced with an MIT Licence, conditions can be found in LICENCE in the crate GitHub repository.
49//! </section>
50
51#![no_std]
52
53//
54// Public modules
55//
56#[cfg(any(driver_model__driver_type = "WDM", driver_model__driver_type = "KMDF"))]
57pub mod errors;
58#[cfg(any(driver_model__driver_type = "WDM", driver_model__driver_type = "KMDF"))]
59pub mod fast_mutex;
60#[cfg(any(driver_model__driver_type = "WDM", driver_model__driver_type = "KMDF"))]
61pub mod grt;
62#[cfg(any(driver_model__driver_type = "WDM", driver_model__driver_type = "KMDF"))]
63pub mod kmutex;
64
65//
66// Private modules
67//
68#[cfg(any(driver_model__driver_type = "WDM", driver_model__driver_type = "KMDF"))]
69mod alloc;