2 files changed, 25 insertions, 4 deletions

diff --git a/embassy-sync/src/blocking_mutex/mod.rs b/embassy-sync/src/blocking_mutex/mod.rs
index 8a4a4c642..62bfc26fb 100644
--- a/embassy-sync/src/blocking_mutex/mod.rs
+++ b/embassy-sync/src/blocking_mutex/mod.rs
@@ -22,6 +22,7 @@ use self::raw::RawMutex;
 ///
 /// In all cases, the blocking mutex is intended to be short lived and not held across await points.
 /// Use the async [`Mutex`](crate::mutex::Mutex) if you need a lock that is held across await points.
+#[derive(Debug)]
 pub struct Mutex<R, T: ?Sized> {
     // NOTE: `raw` must be FIRST, so when using ThreadModeMutex the "can't drop in non-thread-mode" gets
     // to run BEFORE dropping `data`.
@@ -50,6 +51,23 @@ impl<R: RawMutex, T> Mutex<R, T> {
             f(inner)
         })
     }
+
+    /// Creates a critical section and grants temporary mutable access to the protected data.
+    ///
+    /// # Safety
+    ///
+    /// This method is marked unsafe because calling this method re-entrantly, i.e. within
+    /// another `lock_mut` or `lock` closure, violates Rust's aliasing rules. Calling this
+    /// method at the same time from different tasks is safe. For a safe alternative with
+    /// mutable access that never causes UB, use a `RefCell` in a `Mutex`.
+    pub unsafe fn lock_mut<U>(&self, f: impl FnOnce(&mut T) -> U) -> U {
+        self.raw.lock(|| {
+            let ptr = self.data.get() as *mut T;
+            // Safety: we have exclusive access to the data, as long as this mutex is not locked re-entrantly
+            let inner = unsafe { &mut *ptr };
+            f(inner)
+        })
+    }
 }
 
 impl<R, T> Mutex<R, T> {
@@ -104,6 +122,7 @@ impl<T> Mutex<raw::CriticalSectionRawMutex, T> {
 
 impl<T> Mutex<raw::NoopRawMutex, T> {
     /// Borrows the data
+    #[allow(clippy::should_implement_trait)]
     pub fn borrow(&self) -> &T {
         let ptr = self.data.get() as *const T;
         unsafe { &*ptr }
@@ -116,9 +135,9 @@ impl<T> Mutex<raw::NoopRawMutex, T> {
 // There's still a ThreadModeRawMutex for use with the generic Mutex (handy with Channel, for example),
 // but that will require T: Send even though it shouldn't be needed.
 
-#[cfg(any(cortex_m, feature = "std"))]
+#[cfg(any(cortex_m, doc, feature = "std"))]
 pub use thread_mode_mutex::*;
-#[cfg(any(cortex_m, feature = "std"))]
+#[cfg(any(cortex_m, doc, feature = "std"))]
 mod thread_mode_mutex {
     use super::*;
 
diff --git a/embassy-sync/src/blocking_mutex/raw.rs b/embassy-sync/src/blocking_mutex/raw.rs
index a8afcad34..fbb9ece15 100644
--- a/embassy-sync/src/blocking_mutex/raw.rs
+++ b/embassy-sync/src/blocking_mutex/raw.rs
@@ -37,6 +37,7 @@ pub unsafe trait RawMutex {
 /// # Safety
 ///
 /// This mutex is safe to share between different executors and interrupts.
+#[derive(Debug)]
 pub struct CriticalSectionRawMutex {
     _phantom: PhantomData<()>,
 }
@@ -65,6 +66,7 @@ unsafe impl RawMutex for CriticalSectionRawMutex {
 /// # Safety
 ///
 /// **This Mutex is only safe within a single executor.**
+#[derive(Debug)]
 pub struct NoopRawMutex {
     _phantom: PhantomData<*mut ()>,
 }
@@ -87,7 +89,7 @@ unsafe impl RawMutex for NoopRawMutex {
 
 // ================
 
-#[cfg(any(cortex_m, feature = "std"))]
+#[cfg(any(cortex_m, doc, feature = "std"))]
 mod thread_mode {
     use super::*;
 
@@ -145,5 +147,5 @@ mod thread_mode {
         return unsafe { (0xE000ED04 as *const u32).read_volatile() } & 0x1FF == 0;
     }
 }
-#[cfg(any(cortex_m, feature = "std"))]
+#[cfg(any(cortex_m, doc, feature = "std"))]
 pub use thread_mode::*;