cortex_a9::mutex: restore and fix powersaving behaviour, doc

src/cortex_a9/mutex.rs

@@ -3,9 +3,25 @@ use core::sync::atomic::{AtomicU32, Ordering};
 use core::cell::UnsafeCell;
 use super::asm::*;
 
+/// [Power-saving features](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dht0008a/ch01s03s02.html)
+#[inline]
+fn wait_for_update() {
+    wfe();
+}
+
+/// [Power-saving features](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dht0008a/ch01s03s02.html)
+#[inline]
+fn signal_update() {
+    dsb();
+    sev();
+}
+
 const LOCKED: u32 = 1;
 const UNLOCKED: u32 = 0;
 
+/// Mutex implementation for Cortex-A9
+///
+/// [ARM Synchronization Primitives Development Article: Implementing a mutex](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dht0008a/ch01s03s02.html)
 pub struct Mutex<T> {
     locked: AtomicU32,
     inner: UnsafeCell<T>,
@@ -15,6 +31,7 @@ unsafe impl<T: Send> Sync for Mutex<T> {}
 unsafe impl<T: Send> Send for Mutex<T> {}
 
 impl<T> Mutex<T> {
+    /// Constructor, const-fn
     pub const fn new(inner: T) -> Self {
         Mutex{
             locked: AtomicU32::new(UNLOCKED),
@@ -22,8 +39,11 @@ impl<T> Mutex<T> {
         }
     }
 
+    /// Lock the Mutex, blocks when already locked
     pub fn lock(&self) -> MutexGuard<T> {
-        while self.locked.compare_and_swap(UNLOCKED, LOCKED, Ordering::Acquire) != UNLOCKED {}
+        while self.locked.compare_and_swap(UNLOCKED, LOCKED, Ordering::Acquire) != UNLOCKED {
+            wait_for_update();
+        }
         dmb();
         MutexGuard { mutex: self }
     }
@@ -31,10 +51,13 @@ impl<T> Mutex<T> {
     fn unlock(&self) {
         dmb();
         self.locked.store(UNLOCKED, Ordering::Release);
-        dsb();
+
+        signal_update();
     }
 }
 
+/// Returned by `Mutex.lock()`, allows access to data via
+/// `Deref`/`DerefMutx`
 pub struct MutexGuard<'a, T> {
     mutex: &'a Mutex<T>,
 }
@@ -52,6 +75,7 @@ impl<'a, T> DerefMut for MutexGuard<'a, T> {
     }
 }
 
+/// Automatically `Mutex.unlock()` when this reference is dropped
 impl<'a, T> Drop for MutexGuard<'a, T> {
     fn drop(&mut self) {
         self.mutex.unlock();